Java Reference
In-Depth Information
protected boolean traverse(int dir, int viewportWidth, int viewportHeight,
int[] visRect_inout);
protected void traverseOut();
Note
At first glance, you might expect custom items to receive calls on both the traversal methods and
the key event methods when keys are pressed on the device. For example, if the user presses the down arrow
key to move into the item, you might expect both the
traverse()
and
keyPressed()
methods to be called.
In reality, the implementation should keep key events and traversal events unambiguous. Bear in mind that
some devices will have alternate traversal controls (wheels, for example), so the implementation (and your
custom item) should treat the events distinctly.
■
If you do write a custom item that supports internal traversal, you need to pay attention to
the arguments passed to
traverse()
and you need to return
true
to indicate that your item
supports internal traversal. The information passed to the
traverse()
method is as follows:
•
dir
indicates the traversal direction requested by the user. It is one of the following:
Canvas.UP
,
Canvas.DOWN
,
Canvas.LEFT
,
Canvas.RIGHT
, or
CustomItem.NONE
.
•
viewportWidth
and
viewportHeight
indicate the size available for items in the
Form
containing this custom item. (In essence,
viewportWidth
and
viewportHeight
describe
the content area of the
Form
.) These dimensions may be useful for determining the rela-
tionship between an item's choices and the amount of available screen area.
•
visRect_inout
is kind of weird. It is an integer array with four elements. When the
traverse()
method is called,
visRect_inout
describes the region of the custom item's
visible content area. When the
traverse()
method returns,
visRect_inout
should
contain the bounds of the currently selected choice in the item.
If this is starting to sound a little hairy, just wait. The traversal mechanism is flexible
enough to support different kinds of traversal. Some devices may only be able to support
vertical traversal, while others may only support horizontal, and still others may support both.
You can find out the device's traversal capabilities with the
getInteractionModes()
method,
which can return
CustomItem.TRAVERSE_HORIZONTAL
,
CustomItem.TRAVERSE_VERTICAL
, or both.
Depending on the nature of the choices contained in your custom item, you may have to be
flexible about the traversal directions you're receiving and the actual traversal inside the item.
Remember, the
traverse()
method is called when focus first comes to your item. If this
method returns
true
,
traverse()
will be repeatedly called while traversal progresses through
your item. When the user traverses out of your item, return
false
from the
traverse()
method.
This lets the implementation know that internal traversal has ended. Most likely the implemen-
tation will call
traverseOut()
, although this only happens if focus actually moves away from
the item. This may not be the case if the user has reached the end or beginning of the form.
All of this is discussed in meticulous detail in the API documentation for
CustomItem
's
traverse()
method. If you're planning to implement a custom item with internal traversal, go
read the documentation a few times until it all sinks in.
Search WWH ::
Custom Search