package-summary.html

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

  <P>
    In the low-level API, repainting of <CODE>Canvas</CODE> is done
    asynchronously so that several repaint requests may be implemented
    within a single call as an optimization. This means that the
    application requests the repainting by calling the method
    <CODE>repaint()</CODE> of class <CODE>Canvas</CODE> . The actual
    drawing is done in the method <CODE>paint() </CODE>
    -- which is provided by the subclass <CODE>Canvas </CODE>
    -- and does not necessarily happen synchronously to
       <CODE>repaint()</CODE>
    . It may happen later, and several repaint requests may cause one
    single call to <CODE>paint()</CODE> . The application can flush
    the repaint requests by calling <CODE>serviceRepaints()</CODE>
    .</P>
  <P>
    As an example, assume that an application moves a box of width
    <CODE>
      wid</CODE>
    and height <CODE>ht</CODE> from coordinates (<CODE>x1,y1</CODE> )
    to coordinates (<CODE>x2,y2</CODE> ), where <CODE>x2&gt;x1</CODE>
    and <CODE>y2&gt;y1</CODE> : </P>
  <P>
  <TABLE BORDER="2">
    <TR>
      <TD ROWSPAN="1" COLSPAN="1">
        <pre><code>
    // move coordinates of box
    box.x = x2;
    box.y = y2;
    
    // ensure old region repainted (with background)    
    canvas.repaint(x1,y1, wid, ht);
    
    // make new region repainted
    canvas.repaint(x2,y2, wid, ht);
    
    // make everything really repainted
    canvas.serviceRepaints();</code> </pre>
      </TD>
    </TR>
  </TABLE>
  </P>
  <P>
    The last call causes the repaint thread to be scheduled. The
    repaint thread finds the two requests from the event queue and
    repaints the region that is a union of the repaint area: </P>
  <p>
    <TABLE BORDER="2">
    <TR>
      <TD ROWSPAN="1" COLSPAN="1">
        <pre><code>
    graphics.clipRect(x1,y1, (x2-x1+wid), (y2-y1+ht));      
    canvas.paint(graphics);      </code></pre>
      </TD>
    </TR>
  </TABLE></p>
  <P>
    In this imaginary part of an implementation, the call
    <CODE>
      canvas.paint()</CODE>
    causes the application-defined <CODE>paint()</CODE>
    method to be called.</P>
  
  
  <H4>
    Drawing Model</H4>
  <P>
    The primary drawing operation is pixel replacement, which is used
    for geometric rendering operations such as lines and rectangles.
    With offscreen images, support for full transparency is required,
    and support for partial transparency (alpha blending) is
    optional.</P>
  <P>
    A 24-bit color model is provided with 8 bits each for the red,
    green, and blue components of a color. Not all devices support
    24-bit color, so they will map colors requested by the application
    into colors available on the device. Facilities are provided in
    the <CODE>
      Display</CODE>
    class for obtaining device characteristics, such as whether color
    is available and how many distinct gray levels are available. This
    enables applications to adapt their behavior to a device without
    compromising device independence.</P>
  <P>
    Graphics may be rendered either directly to the display or to an
    off-screen image buffer. The destination of rendered graphics
    depends on the origin of the graphics object. A graphics object
    for rendering to the display is passed to the <CODE>Canvas</CODE>
    object's <CODE>paint()</CODE> method. This is the only way to
    obtain a graphics object whose destination is the
    display. Furthermore, applications may draw by using this graphics
    object only for the duration of the <CODE>paint()</CODE>
    method. </P>
  <P>
    A graphics object for rendering to an off-screen image buffer may
    be obtained by calling the <CODE>getGraphics()</CODE> method on
    the desired image. These graphics objects may be held indefinitely
    by the application, and requests may be issued on these graphics
    objects at any time.</P>
  <P>
    The <code>Graphics</code> class has a current color that is set
    with the <code>setColor()</code> method.  All geometric rendering,
    including lines, rectangles, and arcs, uses the current color.
    The pixel representing the current color replaces the destination
    pixel in these operations.  There is no background color.
    Painting of any background be performed explicitly by the
    application using the <code>setColor()</code> and rendering
    calls.  </P>
  <P>
    Support for full transparency is required, and support for partial
    transparency (alpha blending) is optional.  Transparency (both
    full and partial) exists only in off-screen images loaded from PNG
    files or from arrays of ARGB data.  Images created in such a
    fashion are <em>immutable</em> in that the application is
    precluded from making any changes to the pixel data contained
    within the image.  Rendering is defined in such a way that the
    destination of any rendering operation always consists entirely of
    fully opaque pixels. </P>
  
  <H4>
    Coordinate System</H4>
  <P>
    The origin <code>(0,0)</code> of the available drawing area and
    images is in the upper-left corner of the display. The numeric
    values of the x-coordinates monotonically increase from left to
    right, and the numeric values of the y-coordinates monotonically
    increase from top to bottom. Applications may assume that
    horizontal and vertical distances in the coordinate system
    represent equal distances on the actual device display. If the
    shape of the pixels of the device is significantly different from
    square, the implementation of the UI will do the required
    coordinate transformation. A facility is provided for translating
    the origin of the coordinate system. All coordinates are specified
    as integers.</P>
  <P>
    The coordinate system represents locations between pixels, not the
    pixels themselves. Therefore, the first pixel in the upper left
    corner of the display lies in the square bounded by coordinates
    <code>(0,0), (1,0), (0,1), (1,1)</code>.</P>
  <P>
    An application may inquire about the available drawing area by calling
    the following methods of <CODE>Canvas</CODE>
    : </P>
  <P>
  <TABLE BORDER="2">
    <TR>
      <TD ROWSPAN="1" COLSPAN="1">
        <pre><CODE>
    public static final int getWidth();
    public static final int getHeight();    </CODE></pre>
      </TD>
    </TR>
  </TABLE>
  </P>
  
  <H4>
    Font Support</H4>
  <P>
    An application may request one of the font attributes specified
    below.  However, the underlying implementation may use a subset of
    what is specified. So it is up to the implementation to return a
    font that most closely resembles the requested font.</P>
  <P>
    Each font in the system is implemented individually. A programmer
    will call the static <CODE>getFont()</CODE> method instead of
    instantiating new <CODE>Font</CODE> objects. This paradigm
    eliminates the garbage creation normally associated with the use
    of fonts.</P>
  <P>
    The <CODE>Font</CODE> class provides calls that access font
    metrics. The following attributes may be used to request a font
    (from the <CODE>
      Font</CODE>
    class): </P>
  <UL>
    <LI>
      Size: <code>SMALL</code>, <code>MEDIUM</code>,
      <code>LARGE</code>.</LI>
    <LI>
      Face: <code>PROPORTIONAL</code>, <code>MONOSPACE</code>,
      <code>SYSTEM</code>.</LI>
    <LI>
      Style: <code>PLAIN</code>, <code>BOLD</code>, <code>ITALIC</code>,
      <code>UNDERLINED</code>.</LI>
  </UL>
  
  <A NAME="concurrency"></A>
  <H3>Concurrency</H3>
  <P>
    The UI API has been designed to be thread-safe. The methods may be
    called from callbacks, <CODE>TimerTasks</CODE>, or other threads created
    by the application. Also, the implementation generally does not hold any
    locks on objects visible to the application. This means that the
    applications' threads can synchronize with themselves and with the event
    callbacks by locking any object according to a synchronization policy
    defined by the application.  One exception to this rule occurs with the
    <A HREF="../../../javax/microedition/lcdui/Canvas.html#serviceRepaints()"><CODE>Canvas.serviceRepaints</CODE></A> method.  This method calls and awaits
    completion of the <code>paint</code> method.  Strictly speaking,
    <code>serviceRepaints</code> might not call <code>paint</code>
    directly, but instead it might cause another thread to call
    <code>paint</code>.  In either case, <code>serviceRepaints</code>
    blocks until <code>paint</code> has returned.  This is a significant
    point because of the following case.  Suppose the caller of
    <code>serviceRepaints</code> holds a lock that is also needed by the
    <code>paint</code> method.  Since <code>paint</code> might be called
    from another thread, that thread will block trying to acquire the lock.
    However, this lock is held by the caller of <code>serviceRepaints</code>,
    which is blocked waiting for <code>paint</code> to return.  The result
    is deadlock.  In order to avoid deadlock, the caller of
    <code>serviceRepaints</code> <em>must not</em> hold any locks
    needed by the <code>paint</code> method.</P>
  <P>
    The UI API includes also a mechanism similar to other UI toolkits
    for serializing actions with the event stream.  The method
    <A HREF="../../../javax/microedition/lcdui/Display.html#callSerially(java.lang.Runnable)"><CODE>Display.callSerially</CODE></A>
    requests that the <code>run</code> method of a <code>Runnable</code>
    object be called, serialized with the event stream.  Code that uses
    <CODE>serviceRepaints()</CODE> can usually be rewritten to use
    <CODE>callSerially()</CODE>.  The following code illustrates
    this technique:
  </P>
  <P>
  <TABLE BORDER="2">
    <TR>
      <TD ROWSPAN="1" COLSPAN="1">
        <pre><code>
    class MyCanvas extends Canvas {    
        void doStuff() {
            // &lt;code fragment 1&gt;    
            serviceRepaints();
            // &lt;code fragment 2&gt;    
        }
    }    </code> </pre>
      </TD>
    </TR>
  </TABLE>
  </P>
  <P>
    The following code is an alternative way of implementing the same
    functionality:</P>
  <P>
  <TABLE BORDER="2">
    <TR>
      <TD ROWSPAN="1" COLSPAN="1">
        <pre><code>
    class MyClass extends Canvas 
       implements Runnable {            
        void doStuff() {
            // &lt;code fragment 1&gt;
            callSerially(this);
        }

        // called only after all pending repaints served    
        public void run() {
            // &lt;code fragment 2&gt;;
        }
    }    </code> </pre>
      </TD>
    </TR>
  </TABLE>
  </P>
  
  <H3>Implementation Notes</H3>
  <P>
    The implementation of a <code>List</code> or
    <code>ChoiceGroup</code> may include keyboard shortcuts for
    focusing and selecting the choice elements, but the use of these
    shortcuts is not visible to the application program.</P>
  <P>
    In some implementations the UI components -- <code>Screens</code>
    and <code>Items</code> -- will be based on native components. It
    is up to the implementation to free the used resources when the
    Java objects are not needed anymore. One possible implementation
    scenario is a hook in the garbage collector of KVM.</P>
<P>
<DL>
<DT><B>Since: </B><DD>MIDP 1.0</DD>
</DL>
<HR>

<!-- ========== START OF NAVBAR ========== -->
<A NAME="navbar_bottom"><!-- --></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0">
<TR>
<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_bottom_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3">
  <TR ALIGN="center" VALIGN="top">
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <FONT CLASS="NavBarFont1">Class</FONT>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-use.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
  </TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
<strong>MID Profile</strong></EM>
</TD>
</TR>

<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
&nbsp;<A HREF="../../../javax/microedition/io/package-summary.html"><B>PREV PACKAGE</B></A>&nbsp;
&nbsp;<A HREF="../../../javax/microedition/lcdui/game/package-summary.html"><B>NEXT PACKAGE</B></A></FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
  <A HREF="../../../index.html" TARGET="_top"><B>FRAMES</B></A>  &nbsp;
&nbsp;<A HREF="package-summary.html" TARGET="_top"><B>NO FRAMES</B></A></FONT></TD>
</TR>
</TABLE>
<!-- =========== END OF NAVBAR =========== -->

<HR>
<font size="-1"><a href="mailto:[e-mail]">Submit a comment or suggestion</a> Version 2.0 of MID Profile Specification<br>Java is a trademark or registered trademark of Sun Microsystems,  Inc. in the US and other countries. Copyright (c) 1993-2002 Sun Microsystems, Inc. 901 San Antonio Road,Palo Alto, California, 94303, U.S.A.  All Rights Reserved.</font>
</BODY>
</HTML>