Building User Interfaces - Beginning Java ME Platform - page 119

• Handle events : The Canvas class receives low-level events, including key-press,
repeat, and release events, as well as pointer-press, drag, and release events.
• Handle commands : As with other Displayable subclasses, your Canvas implementa-
tion inherits the methods pertaining to the Command infrastructure, including
addCommand , removeCommand , and setCommandListener .
• Draw : Subclasses of Canvas must implement the paint method, which takes a
Graphics instance that you use to draw on the Canvas .
The downside to using the Canvas class is that event handling is not as portable as
the Command and CommandListener classes are. For every keystroke, your Canvas receives a
keyPressed invocation and a keyReleased invocation, and possibly one or more
keyRepeated invocations between the two. The system passes these methods a key code —
that is, an integer indicating the key that you pressed. The Canvas class defines constant
members for keys common to all MIDP devices, including the number keys, the arrow
keys, four game keys, and the fire key (selection key). There may be overlap between
these keys; for example, the game keys may actually be number keys.
Unfortunately, other keys that aren't common to all MIDP devices may have
different key codes, so if you're designing a more complex Canvas subclass that uses
many keys, or one that requires alphanumeric input, you'll end up needing to write
code for each device on which your application will run. One way to do this is to
abstract key-code handling from event handling, in much the same way that the MIDP
platform does; instead of examining key codes directly, use a function to map the key
codes and the logical actions that the key codes represent, so that you can map multi-
ple key codes to a single logical event.
Your Canvas subclass can receive pointer events, too, provided that your application is
running on a platform that supports some kind of pointer (mouse or stylus, presumably).
Some devices have no pointer; you can determine the support for pointer events by
invoking hasPointerEvents , which returns true if the device supports pointer-press and
release events. In a similar vein, the hasPointerMotionEvents method of Canvas returns true
if the device supports drag events from the pointer. Assuming there's support, you receive
events by overriding the pointerPressed , pointerDragged , and pointerReleased methods;
each of these receives two integers, the x and y coordinate for the event.
At any time, the system can signal that the Canvas should redraw itself by invoking
its repaint method. This method comes in two varieties: one that takes the bounds of
the rectangle to redraw, and one that takes no arguments but is equivalent to invoking
repaint with the entire Canvas bounds. The repaint method doesn't do any drawing,
however; that's the responsibility of the paint method. The repaint - paint flow is asyn-
chronous; repaint indicates to the object that it's dirty and should plan on repainting,
while the actual drawing by paint occurs at an unspecified (hopefully short!) time in
the future. This permits applications and the system from triggering needless redraw
operations, and it keeps clients from blocking on the Canvas 's paint operation.