customitem.html

J2ME MIDP2.0 final specification

 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>

 <p>When traversal enters the item, the traversal code
 should initialize its internal traversal
 location to the &quot;first&quot; location appropriate
 for the item's structure and the traversal direction.
 As an example of the latter policy, if
 the traversal direction is <code>DOWN</code>, the initial
 location should be the
 topmost internal element of the item.  Similarly, if the traversal
 direction is <code>UP</code>, the initial location should be the
 bottommost element of the item.
 The <code>CustomItem</code>
 should still choose the &quot;first&quot; location appropriately
 even if its primary axis is orthogonal to the
 axis of traversal.  For example, suppose the traversal
 mode supported is <code>TRAVERSE_VERTICAL</code> but the
 <code>CustomItem</code> is structured as a horizontal row
 of elements.  If the initial traversal direction is
 <code>DOWN</code>, the initial location might be the leftmost
 element, and if the initial traversal direction is
 <code>UP</code>, the initial location might be the rightmost
 element.</p>

 <p>Traversal may enter the item without any specific direction, in
 which case the traversal direction will be <code>NONE</code>.  This may
 occur if the user selects the item directly (e.g., with a pointing
 device), or if the item gains the focus because its containing
 <code>Form</code> has become current. The <code>CustomItem</code>
 should choose a default traversal location.  If the
 <code>CustomItem</code> had been traversed to previously, and if it is
 appropriate for the user interface of the <code>CustomItem</code>, the
 previous traversal location should be restored.</p>

 <p>When traversal occurs within
 the item, the internal traversal location must be moved to the next
 appropriate region in the direction of traversal.  The item must report
 its updated internal traversal location in the
 <code>visRect_inout</code> return parameter as described below and
 return <code>true</code>.  The item will typically provide a highlight
 to display the internal traversal location to the user.  Thus, the item
 will typically also request repaints of the old and new traversal
 locations after each traversal event.  There is no requirement that the
 area the item requests to be repainted is the same as the area returned
 in the <code>visRect_inout