package-summary.html

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

    access to low-level input events. Some applications also need to
    access special, device-specific features. A typical example of
    such an application would be a game.</P>
  <P>
    Using the low-level API, an application can:</P>
  <UL>
    <LI>
      Have full control of what is drawn on the display.</LI>
    <LI>
      Listen for primitive events like key presses and releases.</LI>
    <LI>
      Access concrete keys and other input devices.</LI>
  </UL>
  <P>
    The classes that provide the low-level API are
    <A HREF="../../../javax/microedition/lcdui/Canvas.html"><CODE>Canvas</CODE></A> and
    <A HREF="../../../javax/microedition/lcdui/Graphics.html"><CODE>Graphics</CODE></A>.</P>
  <P>
    Applications that program to the low-level API are not guaranteed
    to be portable, since the low-level API provides the means to
    access details that are specific to a particular device. If the
    application does not use these features, it will be portable.  It
    is recommended that applications use only the platform-independent
    part of the low-level API whenever possible. This means that the
    applications should not directly assume the existence of any keys
    other than those defined in the <CODE>Canvas</CODE> class, and
    they should not depend on a specific screen size. Rather, the
    application game-key event mapping mechanism should be used
    instead of concrete keys, and the application should inquire about
    the size of the display and adjust itself accordingly. </P>
  <H4>
    Class Hierarchy</H4>
  <P>
    The central abstraction of the MIDP's UI is a
    <code>Displayable</code> object, which encapsulates
    device-specific graphics rendering with user input.  Only one
    <code>Displayable</code> may be visible at a time, and and the
    user can see and interact with only contents of that
    <code>Displayable</code>.</P>
  <P>
    The <code>Screen</code> class is a subclass of
    <code>Displayable</code> that takes care of all user interaction
    with high-level user interface component.  The <code>Screen</code>
    subclasses handle rendering, interaction, traversal, and
    scrolling, with only higher-level events being passed on to the
    application.</P>
  <P>
    The rationale behind this design is based on the different display
    and input solutions found in MIDP devices. These differences imply
    that the component layout, scrolling, and focus traversal will be
    implemented differently on different devices. If an application
    were required to be aware of these issues, portability would be
    compromised. Simple screenfuls also organize the user interface
    into manageable pieces, resulting in user interfaces that are easy
    to use and learn. </P>
  <P>
    There are three categories of <code>Displayable</code> objects: </P>
  <UL>
    <LI>
      Screens that encapsulate a
      complex user interface
      component (e.g., classes
      <CODE>List</CODE> or <CODE>TextBox</CODE>).
      The structure of these screens is predefined, and the application
      cannot add other components to these screens. </LI>
    <LI>
      Generic screens (instances of the <CODE>Form</CODE> class) that
      can contain <CODE>Item</CODE> objects to represent user
      interface components.  The application can populate
      <CODE>Form</CODE> objects with an arbitrary number of text,
      image, and other components; however, it is recommended that
      <CODE>Form</CODE> objects be kept simple and that they should be
      used to contain only a few, closely-related user interface
      components.
    </LI>
    <LI>
      Screens that are used in context of the low-level API
      (i.e., subclasses of class <CODE>Canvas</CODE>).</LI>
  </UL>
  <P>
    Each <code>Displayable</code> can have
    a title, a <CODE>Ticker</CODE> and a set of 
    <CODE>Commands</CODE> attached to it. </P>
  <P>
    The class <CODE>Display</CODE> acts as the display manager that is
    instantiated for each active <code>MIDlet</code> and provides
    methods to retrieve information about the device's display
    capabilities. A <CODE>Displayable</CODE> is made visible by
    calling the <CODE>setCurrent()</CODE> method of
    <CODE>Display</CODE>.  When a <CODE>Displayable</CODE> is made
    current, it replaces the previous <CODE>Displayable</CODE>.  </P>
  
  <H4>
    Class Overview</H4>
  <P>
    It is anticipated that most applications will utilize screens with
    predefined structures like
    <CODE>List</CODE>
    , <CODE>TextBox</CODE>
    , and <CODE>Alert</CODE>
    . These classes are used in the following ways:</P>
  <UL>
    <LI>
      <CODE>List</CODE>
      is used when the user should select from a predefined set of
      choices.</LI>
    <LI>
      <CODE>TextBox</CODE>
      is used when asking textual input.</LI>
    <LI>
      <CODE>Alert</CODE>
      is used to display temporary messages containing text and images.
    </LI>
  </UL>
  <P>
    A special class <CODE>Form</CODE> is defined for cases where
    screens with a predefined structure are not sufficient. For
    example, an application may have two <CODE>TextFields</CODE>, or a
    <CODE>TextField</CODE> and a simple <CODE>ChoiceGroup</CODE>
    . Although this class (<CODE>Form</CODE> ) allows creation of
    arbitrary combinations of components, developers should keep the
    limited display size in mind and create only simple
    <CODE>Forms</CODE> .</P>
  <P>
    <CODE>Form</CODE> is designed to contain a small number of closely
    related UI elements.  These elements are the subclasses of
    <CODE>Item</CODE>: <CODE>ImageItem</CODE>,
    <CODE>StringItem</CODE>, <CODE>TextField</CODE>,
    <CODE>ChoiceGroup</CODE>, <CODE>Gauge</CODE>, and
    <CODE>CustomItem</CODE>. The classes <CODE>ImageItem</CODE> and
    <CODE>StringItem</CODE> are convenience classes that make certain
    operations with <CODE>Form</CODE> and <CODE>Alert</CODE>
    easier. By subclassing <CODE>CustomItem</CODE> application
    developers can introduce <CODE>Items</CODE> with a new visual
    representation and interactive elements. If the components do not
    all fit on the screen, the implementation may either make the form
    scrollable or implement some components so that they can either
    popup in a new screen or expand when the user edits the
    element.</P>
  
  
  <H4>
    Interplay with Application Manager</H4>
  <P>
    The user interface, like any other resource in the API, is to be
    controlled according to the principle of MIDP application
    management.  The UI expects the following conditions from the
    application management software: </P>
  <UL>
    <LI>
      <CODE>getDisplay()</CODE> is callable starting from
      <CODE>MIDlet</CODE>'s constructor until
      <CODE>destroyApp()</CODE> has returned. </LI>
    <LI>
      The <code>Display</code> object is the same until
      <CODE>destroyApp()</CODE> is called. </LI>
    <LI>
      The <code>Displayable</code> object set by
      <CODE>setCurrent()</CODE> is not changed by the application
      manager. </LI>
  </UL>
  <P>
    The application manager assumes that the application behaves as
    follows with respect to the <code>MIDlet</code> events: </P>
  <UL>
    <LI>
      <CODE>startApp</CODE>
      - The application may call <CODE>setCurrent()</CODE>
      for the first screen. The application manager makes
      <code>Displayable</code> really visible when <CODE>
      startApp()</CODE> returns. Note that <CODE>startApp()</CODE>
      can be called several times if <CODE>pauseApp()</CODE> is called
      in between. This means that initialization should not take
      place, and the application should not accidentally switch to
      another screen with <CODE>setCurrent()</CODE> . </LI>
    <LI>
      <CODE>pauseApp</CODE>
      - The application should release as many threads as
      possible. Also, if starting with another screen when the
      application is re-activated, the new screen should be set with
      <CODE>setCurrent()</CODE> .</LI>
    <LI>
      <CODE>destroyApp</CODE>
      - The application may delete created objects.</LI>
  </UL>
  
  
  <A NAME="events"></A>
  <H3>Event Handling</H3>
  <P>
    User interaction causes events, and the implementation notifies
    the application of the events by making corresponding
    callbacks. There are four kinds of UI callbacks:</P>
  <UL>
    <LI>
      Abstract commands that are part of the high-level API</LI>
    <LI>
      Low-level events that represent single key presses and releases
      (and pointer events, if a pointer is available)</LI>
    <LI>
      Calls to the <CODE>paint()</CODE> method of a
      <CODE>Canvas</CODE> class</LI>
    <LI>
      Calls to a <CODE>Runnable</CODE> object's <CODE>run()</CODE>
      method requested by a call to <CODE>callSerially()</CODE> of
      class <CODE>Display</CODE>
    </LI>
  </UL>
  <P>
    All UI callbacks are serialized, so they will never occur in
    parallel. That is, the implementation will
    never call an callback before a prior call to <em>any</em>
    other callback has returned.  This property enables applications
    to be assured that processing of a previous user event will have
    completed before the next event is delivered.  If multiple UI
    callbacks are pending, the next is called as soon as possible after
    the previous UI callback returns.  The implementation also
    guarantees that the call to <CODE>run()</CODE> requested by a call
    to <CODE>callSerially()</CODE> is made after any pending repaint
    requests have been satisfied.</P>
  <P>
    There is one exception to the callback serialization rule, which occurs
    when the <A HREF="../../../javax/microedition/lcdui/Canvas.html#serviceRepaints()"><CODE>Canvas.serviceRepaints</CODE></A> method is called.  This method causes
    the the <code>Canvas.paint</code> method to be called and waits
    for it to complete.  This occurs even if the caller of
    <code>serviceRepaints</code> is itself within an active callback.
    There is further discussion of this issue 
    <A HREF="#concurrency">below</A>.</P>
  <P>
    The following callbacks are all serialized with respect to each other:
    </P>
  <UL>
    <li> <A HREF="../../../javax/microedition/lcdui/Canvas.html#hideNotify()"><CODE>Canvas.hideNotify</CODE></A> </li>
    <li> <A HREF="../../../javax/microedition/lcdui/Canvas.html#keyPressed(int)"><CODE>Canvas.keyPressed</CODE></A> </li>
    <li> <A HREF="../../../javax/microedition/lcdui/Canvas.html#keyRepeated(int)"><CODE>Canvas.keyRepeated</CODE></A> </li>
    <li> <A HREF="../../../javax/microedition/lcdui/Canvas.html#keyReleased(int)"><CODE>Canvas.keyReleased</CODE></A> </li>
    <li> <A HREF="../../../javax/microedition/lcdui/Canvas.html#paint(javax.microedition.lcdui.Graphics)"><CODE>Canvas.paint</CODE></A> </li>
    <li> <A HREF="../../../javax/microedition/lcdui/Canvas.html#pointerDragged(int, int)"><CODE>Canvas.pointerDragged</CODE></A> </li>
    <li> <A HREF="../../../javax/microedition/lcdui/Canvas.html#pointerPressed(int, int)"><CODE>Canvas.pointerPressed</CODE></A> </li>
    <li> <A HREF="../../../javax/microedition/lcdui/Canvas.html#pointerReleased(int, int)"><CODE>Canvas.pointerReleased</CODE></A> </li>
    <li> <A HREF="../../../javax/microedition/lcdui/Canvas.html#showNotify()"><CODE>Canvas.showNotify</CODE></A> </li>
    <li> <A HREF="../../../javax/microedition/lcdui/Canvas.html#sizeChanged(int, int)"><CODE>Canvas.sizeChanged</CODE></A> </li>
    <li> <A HREF="../../../javax/microedition/lcdui/CommandListener.html#commandAction(javax.microedition.lcdui.Command, javax.microedition.lcdui.Displayable)"><CODE>CommandListener.commandAction</CODE></A> </li>
    <li> <A HREF="../../../javax/microedition/lcdui/CustomItem.html#getMinContentHeight()"><CODE>CustomItem.getMinContentHeight</CODE></A> </li>
    <li> <A HREF="../../../javax/microedition/lcdui/CustomItem.html#getMinContentWidth()"><CODE>CustomItem.getMinContentWidth</CODE></A> </li>
    <li> <A HREF="../../../javax/microedition/lcdui/CustomItem.html#getPrefContentHeight(int)"><CODE>CustomItem.getPrefContentHeight</CODE></A> </li>
    <li> <A HREF="../../../javax/microedition/lcdui/CustomItem.html#getPrefContentWidth(int)"><CODE>CustomItem.getPrefContentWidth</CODE></A> </li>
    <li> <A HREF="../../../javax/microedition/lcdui/CustomItem.html#hideNotify()"><CODE>CustomItem.hideNotify</CODE></A> </li>
    <li> <A HREF="../../../javax/microedition/lcdui/CustomItem.html#keyPressed(int)"><CODE>CustomItem.keyPressed</CODE></A> </li>
    <li> <A HREF="../../../javax/microedition/lcdui/CustomItem.html#keyRepeated(int)"><CODE>CustomItem.keyRepeated</CODE></A> </li>
    <li> <A HREF="../../../javax/microedition/lcdui/CustomItem.html#keyReleased(int)"><CODE>CustomItem.keyReleased</CODE></A> </li>
    <li> <A HREF="../../../javax/microedition/lcdui/CustomItem.html#paint(javax.microedition.lcdui.Graphics, int, int)"><CODE>CustomItem.paint</CODE></A> </li>
    <li> <A HREF="../../../javax/microedition/lcdui/CustomItem.html#pointerDragged(int, int)"><CODE>CustomItem.pointerDragged</CODE></A> </li>
    <li> <A HREF="../../../javax/microedition/lcdui/CustomItem.html#pointerPressed(int, int)"><CODE>CustomItem.pointerPressed</CODE></A> </li>
    <li> <A HREF="../../../javax/microedition/lcdui/CustomItem.html#pointerReleased(int, int)"><CODE>CustomItem.pointerReleased</CODE></A> </li>
    <li> <A HREF="../../../javax/microedition/lcdui/CustomItem.html#showNotify()"><CODE>CustomItem.showNotify</CODE></A> </li>
    <li> <A HREF="../../../javax/microedition/lcdui/CustomItem.html#sizeChanged(int, int)"><CODE>CustomItem.sizeChanged</CODE></A> </li>
    <li> <A HREF="../../../javax/microedition/lcdui/CustomItem.html#traverse(int, int, int, int[])"><CODE>CustomItem.traverse</CODE></A> </li>
    <li> <A HREF="../../../javax/microedition/lcdui/CustomItem.html#traverseOut()"><CODE>CustomItem.traverseOut</CODE></A> </li>
    <li> <A HREF="../../../javax/microedition/lcdui/Displayable.html#sizeChanged(int, int)"><CODE>Displayable.sizeChanged</CODE></A> </li>
    <li> <A HREF="../../../javax/microedition/lcdui/ItemCommandListener.html#commandAction(javax.microedition.lcdui.Command, javax.microedition.lcdui.Item)"><CODE>ItemCommandListener.commandAction</CODE></A> </li>
    <li> <A HREF="../../../javax/microedition/lcdui/ItemStateListener.html#itemStateChanged(javax.microedition.lcdui.Item)"><CODE>ItemStateListener.itemStateChanged</CODE></A> </li>
    <li> <code>Runnable.run</code> resulting from a call to
         <A HREF="../../../javax/microedition/lcdui/Display.html#callSerially(java.lang.Runnable)"><CODE>Display.callSerially</CODE></A> </li>
  </UL>

  <P>
    Note that <A HREF="../../../java/util/Timer.html"><CODE>Timer</CODE></A>
    events are not considered UI events.
    Timer callbacks may run concurrently with UI event
    callbacks, although <A HREF="../../../java/util/TimerTask.html"><CODE>TimerTask</CODE></A>
    callbacks scheduled on the same <code>Timer</code> are
    serialized with each other.
    Applications that use timers must guard their
    data structures against concurrent access from timer threads
    and UI event callbacks.  Alternatively, applications may have
    their timer callbacks use
    <A HREF="../../../javax/microedition/lcdui/Display.html#callSerially(java.lang.Runnable)"><CODE>Display.callSerially</CODE></A>
    so that work triggered by timer events can be serialized with
    the UI event callbacks.</P>
  
  <H4>
    Abstract Commands</H4>
  <P>
    Since MIDP UI is highly abstract, it does not dictate any concrete
    user interaction technique like soft buttons or menus. Also,
    low-level user interactions such as traversal or scrolling are not
    visible to the application. MIDP applications define
    <CODE>Commands</CODE> , and the implementation may manifest these
    via either soft buttons, menus, or whatever mechanisms are
    appropriate for that device.</P>
  <P>
    <code>Commands</code> are installed to a <CODE>Displayable</CODE>
    (<CODE>Canvas</CODE> or <CODE> Screen</CODE> ) with a method
    <CODE>addCommand</CODE> of class <CODE>Displayable</CODE> .</P>
  <P>
    The native style of the device may assume that certain types of
    commands are placed on standard places. For example, the
    &quot;go-back&quot; operation may always be mapped to the right
    soft button. The <CODE>Command</CODE> class allows the application
    to communicate such a semantic meaning to the implementation so
    that these standard mappings can be effected.</P>
  <P>
    The implementation does not actually implement any of the
    semantics of the <CODE>Command</CODE>.  The attributes of a
    <CODE>Command</CODE> are used only for mapping it onto the user
    interface.  The actual semantics of a <CODE>Command</CODE> are
    always implemented by the application in a
    <CODE>CommandListener</CODE>.</P>
  <P>
    <CODE>Command</CODE> objects have attributes:</P>
  <UL>
    <LI>Label:
      Shown to the user as a hint. A single <CODE>Command</CODE> can
      have two versions of labels: short and long. The implementation
      decides whether the short or long version is appropriate for a
      given situation.  For example, an implementaion can choose to
      use a short version of a given <CODE>Command</CODE> near a soft
      button and the long version of the <CODE>Command</CODE> in a
      menu.</LI>
    <LI>Type: