customitem.html

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

 <code>CustomItem</code> or if the container's layout algorithm has 
 already computed a tentative width at the time of this call.  The 
 subclass must not assume that the tentative width passed or the
 preferred height returned will be granted.
 The actual size granted is reported in the
 <A HREF="../../../javax/microedition/lcdui/CustomItem.html#sizeChanged(int, int)"><CODE>sizeChanged</CODE></A> and <A HREF="../../../javax/microedition/lcdui/CustomItem.html#paint(javax.microedition.lcdui.Graphics, int, int)"><CODE>paint</CODE></A> methods.
 </p><DD><DL>
<DT><B>Parameters:</B><DD><CODE>width</CODE> - the tentative content width in pixels, or -1 if a
 tentative width has not been computed<DT><B>Returns:</B><DD>the preferred content height in pixels</DL>
</DD>
</DL>
<HR>

<A NAME="sizeChanged(int, int)"><!-- --></A><H3>
sizeChanged</H3>
<PRE>
protected void <B>sizeChanged</B>(int&nbsp;w,
                           int&nbsp;h)</PRE>
<DL>
<DD>Implemented by the subclass in order to handle size change events.
 This method is called by the system when the size of the content area
 of this <code>CustomItem</code> has changed.

 <p>If the size of a <code>CustomItem</code> changes while it is
 visible on the display, it may trigger an automatic
 repaint request.  If this occurs, the call to
 <code>sizeChanged</code> will occur prior to the call to
 <code>paint</code>.  If the <code>CustomItem</code> has become
 smaller, the implementation may choose not to trigger a repaint
 request if the remaining contents of the <code>CustomItem</code>
 have been preserved.  Similarly, if the <code>CustomItem</code>
 has become larger, the implementation may choose to trigger a
 repaint only for the new region.  In both cases, the preserved
 contents must remain stationary with respect to the origin of the
 <code>CustomItem</code>.  If the size change is significant to
 the contents of the <code>CustomItem</code>, the application must
 explicitly issue a repaint request for the changed areas.  Note
 that the application's repaint request should not cause multiple
 repaints, since it can be coalesced with repaint requests that
 are already pending.</p>

 <p>If the size of the item's content area
 changes while it is not visible, calls to this method may be deferred.
 If the size had changed while the item was not visible,
 <code>sizeChanged</code> will be called at least once before the item
 becomes visible once again.</p>

 <p>The default implementation of this method does
 nothing.</p><DD><DL>
<DT><B>Parameters:</B><DD><CODE>w</CODE> - the new width of the item's content area<DD><CODE>h</CODE> - the new height of the item's content area</DL>
</DD>
</DL>
<HR>

<A NAME="invalidate()"><!-- --></A><H3>
invalidate</H3>
<PRE>
protected final void <B>invalidate</B>()</PRE>
<DL>
<DD>Signals that the <code>CustomItem's</code> size and traversal
 location need to be updated. 
 This method is intended to be called by <code>CustomItem</code> 
 subclass code to inform the implementation that the size of 
 the <code>CustomItem's</code> content area or the internal
 traversal location might need to change.  
 This often occurs if the contents of the <code>CustomItem</code>
 are modified.  A call to this method will return immediately, and it
 will cause the container's layout algorithm to run at some point in the
 future, possibly resulting in calls to
 
 <A HREF="../../../javax/microedition/lcdui/CustomItem.html#getMinContentHeight()"><CODE>getMinContentHeight</CODE></A>,
 <A HREF="../../../javax/microedition/lcdui/CustomItem.html#getMinContentWidth()"><CODE>getMinContentWidth</CODE></A>,
 <A HREF="../../../javax/microedition/lcdui/CustomItem.html#getPrefContentHeight(int)"><CODE>getPrefContentHeight</CODE></A>,
 <A HREF="../../../javax/microedition/lcdui/CustomItem.html#getPrefContentWidth(int)"><CODE>getPrefContentWidth</CODE></A>,
 <A HREF="../../../javax/microedition/lcdui/CustomItem.html#sizeChanged(int, int)"><CODE>sizeChanged</CODE></A>, or
 <A HREF="../../../javax/microedition/lcdui/CustomItem.html#traverse(int, int, int, int[])"><CODE>traverse</CODE></A>.
 
 The <A HREF="../../../javax/microedition/lcdui/CustomItem.html#paint(javax.microedition.lcdui.Graphics, int, int)"><CODE>paint</CODE></A> method may also be called if
 repainting is necessary as a result of the layout operation.  
 If the content size is invalidated while the 
 <code>CustomItem</code> is not visible, the
 layout operation may be deferred.  The <code>traverse</code> method 
 will be called if the <code>CustomItem</code> contains the current 
 traversal location at the time <code>invalidate</code> is called.</DL>
<HR>

<A NAME="paint(javax.microedition.lcdui.Graphics, int, int)"><!-- --></A><H3>
paint</H3>
<PRE>
protected abstract void <B>paint</B>(<A HREF="../../../javax/microedition/lcdui/Graphics.html">Graphics</A>&nbsp;g,
                              int&nbsp;w,
                              int&nbsp;h)</PRE>
<DL>
<DD>Implemented by the subclass to render the item within its container.
 At the time of the call, the <code>Graphics</code> context's
 destination is the content area of this <code>CustomItem</code>
 (or back buffer for it).  The
 Translation is set so that the upper left corner of the content area is
 at <code>(0,0)</code>, and the clip is set to the area to be painted.
 The application must paint every pixel within the given clip area.  The
 item is allowed to modify the clip area, but the system must not allow
 any modification to result in drawing outside the bounds of the item's
 content area.  The <code>w</code> and <code>h</code> passed
 in are the width and height of the
 content area of the item.  These values will always be equal to the
 values passed with the most recent call to <code>sizeChanged()</code>;
 they are passed here as well for convenience.

 <p>Other values of the <code>Graphics</code> object are as follows:</p>
 <UL>
 <LI>the current color is black;</LI>
 <LI>the font is the same as the font returned by
 <A HREF="../../../javax/microedition/lcdui/Font.html#getDefaultFont()"><CODE>Font.getDefaultFont()</CODE></A>;</LI>
 <LI>the stroke style is <A HREF="../../../javax/microedition/lcdui/Graphics.html#SOLID"><CODE>SOLID</CODE></A>;</LI>
 </UL>

 <p>The <code>paint()</code> method will be called only after
 <code>showNotify()</code> call on this item and before a subsequent
 <code>hideNotify()</code> call on this item, in other words, only when
 at least a portion of the item is actually visible on the display.
 In addition, the <code>paint()</code> method will be called only
 if the item's width and height are both greater than zero.</p><DD><DL>
<DT><B>Parameters:</B><DD><CODE>g</CODE> - the <code>Graphics</code> object to be used for
 rendering the item<DD><CODE>w</CODE> - current width of the item in pixels<DD><CODE>h</CODE> - current height of the item in pixels</DL>
</DD>
</DL>
<HR>

<A NAME="repaint()"><!-- --></A><H3>
repaint</H3>
<PRE>
protected final void <B>repaint</B>()</PRE>
<DL>
<DD>Called by subclass code to request that the item be repainted.  If this
 item is visible on the display, this will result in a call to 
 <code>paint()</code> the next time the <code>CustomItem</code> 
 is to be displayed.  The <code>CustomItem</code>
 subclass should call this method when the item's internal state has
 been updated such that its visual representation needs to be updated.</DL>
<HR>

<A NAME="repaint(int, int, int, int)"><!-- --></A><H3>
repaint</H3>
<PRE>
protected final void <B>repaint</B>(int&nbsp;x,
                             int&nbsp;y,
                             int&nbsp;w,
                             int&nbsp;h)</PRE>
<DL>
<DD>Called by subclass code to request that the specified rectangular area
 of the item be repainted.  If that area is visible on the display, this
 will result in call to <code>paint</code> with graphics set to 
 include the specified rectangular area.  
 The area is specified relative to the <code>CustomItem's</code>
 content area.  
 The <code>CustomItem</code> should call this method when the item's
 internal state has been updated and only part of the visual
 representation needs to be updated.<DD><DL>
<DT><B>Parameters:</B><DD><CODE>x</CODE> - the x coordinate of the rectangular area to be updated<DD><CODE>y</CODE> - the y coordinate of the rectangular area to be updated<DD><CODE>w</CODE> - the width of the rectangular area to be updated<DD><CODE>h</CODE> - the height of the rectangular area to be updated</DL>
</DD>
</DL>
<HR>

<A NAME="traverse(int, int, int, int[])"><!-- --></A><H3>
traverse</H3>
<PRE>
protected boolean <B>traverse</B>(int&nbsp;dir,
                           int&nbsp;viewportWidth,
                           int&nbsp;viewportHeight,
                           int[]&nbsp;visRect_inout)</PRE>
<DL>
<DD>Called by the system when traversal has entered the item or has
 occurred within the item.  The direction of traversal and the item's
 visible rectangle are passed into the method.  The method must do one
 of the following: it must either update its state information
 pertaining to its internal traversal location, set the return rectangle
 to indicate a region associated with this location, and return
 <code>true</code>; or, it must return <code>false</code> to indicate
 that this item does not support internal traversal, or that that
 internal traversal has reached the edge of the item and that traversal
 should proceed to the next item if possible.

 <p>The implementation indicates support for internal traversal within a
 <code>CustomItem</code> by setting one or both of the
 <code>TRAVERSE_HORIZONTAL</code> or
 <code>TRAVERSE_VERTICAL</code> bits in the value returned by the
 <code>getInteractionModes</code>
 method.  The <code>dir</code> parameter indicates the direction of
 traversal by using <code>Canvas</code> game actions 
 <code>Canvas.UP</code>, <code>Canvas.DOWN</code>,
 <code>Canvas.LEFT</code>, and <code>Canvas.RIGHT</code>, or the
 value <code>NONE</code>, which indicates that there is no specific
 direction associated with this traversal event.
 If the <code>TRAVERSE_HORIZONTAL</code> bit is set,
 this indicates that the <code>Canvas.LEFT</code> and 
 <code>Canvas.RIGHT</code> values will be
 used to indicate the traversal direction.  
 If the <code>TRAVERSE_VERTICAL</code> bit
 is set, this indicates that the <code>Canvas.UP</code> and
 <code>Canvas.DOWN</code> values will
 be used to indicate the traversal direction.  If both bits are set, all
 four direction values may be used for the traversal direction,
 indicating that the item should perform two-dimensional traversal.  The
 <code>dir</code> parameter may have the value <code>NONE</code> under
 any combination of the <code>TRAVERSE_VERTICAL</code> and
 <code>TRAVERSE_HORIZONTAL</code> bits.
 </p>

 <p>Although <code>Canvas</code> game actions are used to indicate the
 traversal direction, this does not imply that the keys mapped to these
 game actions are being used for traversal, nor that that keys are being
 used for traversal at all.</p>

 <p>The <code>viewportWidth</code> and <code>viewportHeight</code>
 parameters indicate the size of the viewable area the item's container
 has granted to its items.  This represents the largest area of the
 item that is likely to be visible at any given time.</p>

 <p>The <code>visRect_inout</code> parameter is used both for passing
 information into this method and for returning information from this
 method.  It must be an <code>int[4]</code> array.  The information in
 this array is a rectangle of the form <code>[x,y,w,h]</code>
 where <code>(x,y)</code> is the
 location of the upper-left corner of the rectangle relative to the
 item's origin, and <code>(w,h)</code> are the width and 
 height of the rectangle.
 The return values placed into this array are significant only when the
 <code>traverse()</code> method returns <code>true</code>.  
 The values are ignored if
 the <code>traverse()</code> method returns <code>false</code>.</p>

 <p>When this method is called, the <code>visRect_inout</code> array
 contains a rectangle representing the region of the item that is
 currently visible.  This region might have zero area if no part of the
 item is visible, for example, if it is scrolled offscreen.  The
 semantics of the rectangle returned are discussed below.</p>

 <p>The <code>CustomItem</code> must maintain state that tracks 
 whether traversal is
 within this item, and if it is, it must also record the current
 internal location.  Initially, traversal is outside the item.  The
 first call to the <code>traverse()</code> method indicates 
 that traversal has
 entered the item.  Subsequent calls to this method indicate that
 traversal is occurring within this item.  Traversal remains within the
 item until the <code>traverseOut</code> method is called.  
 The <code>CustomItem</code> must keep
 track of its traversal state so that it can distinguish traversal
 <em>entering</em> the item from traversal <em>within</em> the item.
 </p>