Programming Wireless Devices with the Java2 Platform

11.1 The Canvas API

To directly use the display and the low-level user interface API, the developer uses the Graphics and Canvas classes. The Canvas class provides the display surface, its dimensions, and callbacks used to handle key and pointer events and to paint the display when requested. The methods of this class must be overridden by the developer to respond to events and to paint the screen when requested.

The Graphics class provides methods to paint lines, rectangles, arcs, text, and images to a Canvas or an Image.

The combination of the event-handling capabilities of the Canvas and the drawing capabilities of the Graphics class allows applications to have complete control over the application region of the screen. These low-level classes can be used, for example, to create new screens, implement highly interactive games, and manipulate images to provide rich and compelling displays for J2ME devices.

11.1.1 Canvas Dimensions

A Canvas does not necessarily have access to the entire screen of a J2ME device. Certain areas of the screen may be reserved for other purposes such as displaying network and battery information. In addition, the use of a title, Ticker, and Commands will further reduce the area available to a Canvas.

The current dimensions of a Canvas can be obtained by calling the methods getWidth and getHeight. Furthermore, the sizeChanged method of class Canvas is called whenever the dimensions of the Canvas change, thereby allowing it to update its layout based on the new size.

If an application needs to have as much screen space as possible, the setFullScreenMode method may be called to maximize the available area. When full screen mode is enabled, the Ticker and title are not shown even if they have been added to the Canvas. Commands are still shown, although the device may minimize the space used to display them; some devices may also hide system status indicators to maximize the area available for the Canvas.

11.1.2 Redrawing Mechanism

The application is responsible for redrawing the screen whenever repainting is requested. The application implements the paint method in its subclass of Canvas. Painting of the screen is done on demand so that the device can optimize the use of graphics and screen resources, for example, by coalescing several repaint requests into a single call to the paint method of class Canvas.

Requests to repaint the screen are made automatically by the device as needed; for example, when a Canvas is first shown or when a system dialog has been shown in front of the Canvas and then dismissed. The application itself may also request a repaint of the entire display by calling the repaint method of the Canvas object. If only part of the screen needs to be updated, another repaint method can be given the location, width, and height of the region that needs to be updated.

When the paint method is called, the clip region of the provided Graphics object corresponds to the region that needs to be painted (see Section 11.3.2, "Clipping.") The paint method is responsible for rendering every pixel within the clip region and should not make assumptions about the current state of the pixels. Rendering operations will not affect pixels that lie outside of the clip region. The Canvas cannot render on top of other items on the screen such as the areas occupied by the title or Commands.

The performance of graphic-intensive applications can be enhanced greatly by requesting repaints only for the region of the Canvas that changed, and implementing the paint method to only paint the area within the clip region.

Since painting is done asynchronously, the application might need to wait for repaint requests to be completed before it can continue. The Canvas.serviceRepaints method blocks until all of the repaint requests queued have resulted in a paint call.

If the device is double buffering the display, the Graphics.isDoubleBuffered method returns true. If so, the application need not separately buffer the drawing to get a clean update of the display. Otherwise, the application might be able to optimize its display updates by creating images before they are needed, and then drawing them to the display in its paint method. Use of images is described in Section 11.4, "Creating and Using Images."

11.1.3 Drawing Model

Graphics may be rendered either directly to the display or to an off-screen Image. The destination of the rendered graphics depends on the source of the Graphics object. A Graphics object for rendering to the display is passed to the Canvas object's paint method. This is the only way to obtain a Graphics object whose destination is the display. The applications may draw using this Graphics object only for the duration of the paint method.

A Graphics object for rendering to an off-screen image is obtained by calling the Image.getGraphics method on the desired Image. The Graphics object may be held indefinitely by the application, and drawing methods may be invoked on these Graphics objects at any time.

11.1.4 Canvas Visibility

The display on a device is shared among native applications and MIDP applications. A particular application might or might not be displayed on the screen. When the application's choice of the current screen is a Canvas, the Canvas is notified when its visibility changes. The Canvas.showNotify and Canvas.hideNotify methods are invoked automatically on the Canvas when it is shown and hidden, respectively. The application should override these methods to be informed of changes in visibility. The paint method of the Canvas is called automatically when it is made visible, so the application does not need to call repaint explicitly. Show and hide notifications are useful if, for example, the Canvas is providing an animation that it should start when shown and stop when hidden.