Building User Interfaces - Beginning Java ME Platform - page 122

that specifies which events the device will pass to your CustomItem . The actual values for
the bit mask are provided as fields of CustomItem , and include the values KEY_PRESS ,
KEY_RELEASE , KEY_REPEAT , POINTER_PRESS , POINTER_DRAG , and POINTER_REPEAT . For each kind of
event you intend to support, you must implement the appropriate method, which the
system will invoke to inform your subclass that there's an event of that type ready for it to
process. These methods are the same as for the Canvas class:
• keyPressed : Handles key presses by key code
• keyReleased : Handles key releases by key code
• keyRepeated : Handles repeated key presses (when you press and hold a key) by
key code
• pointerPressed : Handles a pen-down or mouse-down at a coordinate
• pointerDragged : Handles a user dragging the pointer to a new coordinate
• pointerReleased : Handles a pen-up or mouse-up at a coordinate
In addition to these events, you must also handle focus events, which the MIDP
specification confusingly calls traversal operations (presumably because they're gener-
ated as you traverse the parent). Traversal operations give you a way of knowing when
your CustomItem is active and from which direction you arrived at the CustomItem .For
example, a CustomItem that displays richly formatted text that can scroll outside its con-
tent area might wish to show the last pieces of text if it's entered from below, or the first
piece of text it contains when entered from above. To do this, you must implement
CustomItem.traverse , which the caller gives four pieces of information.
The first argument indicates the direction from which you navigated into the
CustomItem . The second and third arguments give the width and height of the viewable
area that the item's container has given its item. From this, you can assume that this is
the largest bound your item will be given to draw, although its actual content bounds will
be passed to the paint method. The final argument is an array indicating a rectangle
bound in the form [x, y, w, h] . When the container calls traverse , it contains the rec-
tangle currently visible; when your traverse method exits, it should contain the bounds
of the rectangle relevant to the viewer. Thus, if your CustomItem contains more informa-
tion than its content area, you should pass the region to be displayed in this rectangle.
The view system may invoke traverse to indicate that a CustomItem has focus, or, once
focused, to indicate that a subitem in the CustomItem should be focused. For example, a
CustomItem implementing a grid of cells (such as a spreadsheet) receives traverse invoca-
tions for each directional arrow press, and it draws its contents so that the currently
selected cell is indicated in some way. To keep your CustomItem focused and receiving
traversal events, your CustomItem.traverse method must return true . To indicate that
navigation of your CustomItem is complete—that the user has traversed out of the item—
return false from traverse .