MID Profile

javax.microedition.lcdui
Class Canvas

java.lang.Object
  |
  +--javax.microedition.lcdui.Displayable
        |
        +--javax.microedition.lcdui.Canvas

public abstract class Canvas
extends Displayable

The Canvas class is a base class for writing applications that need to handle low-level events and to issue graphics calls for drawing to the display. Game applications will likely make heavy use of the Canvas class. From an application development perspective, the Canvas class is interchangeable with standard Screen classes, so an application may mix and match Canvas with high-level screens as needed. For example, a List screen may be used to select the track for a racing game, and a Canvas subclass would implement the actual game.

The Canvas provides the developer with methods to handle game actions, key events, and pointer events (if supported by the device). Static methods are also provided to identify the device's capabilities and keyboard mapping. The key events are directly bound to concrete keys on the device and applications using them directly might not be fully portable to different devices. Portable applications should rely on game actions: UP, DOWN, LEFT, RIGHT, FIRE, GAME_A, GAME_B, GAME_C. and GAME_D.

The canvas class requires applications to subclass it in order to use it. The paint() method is declared abstract and so the application must provide an implementation in its subclass. Other event-reporting methods are not declared abstract, and their default implementations are empty (that is, they do nothing). This allows the application to override only the methods that report events in which the application has interest.

This is in contrast to the Screen classes, which allow the application to define listeners and to register them with instances of the Screen classes. This style is not used for the canvas class, because several new listener interfaces would need to be created, one for each kind of event that might be delivered. An alternative would be to have fewer listener interfaces, but this would require listeners to filter out events in which they had no interest.

Key Events

Applications receive keystroke events in which the individual keys are named within a space of key codes. Every key for which events are reported to MIDP applications is assigned a key code. The key code values are unique for each hardware key unless two keys are obvious synonyms for each other. MIDP defines the following key codes: KEY_NUM0, KEY_NUM1, KEY_NUM2, KEY_NUM3, KEY_NUM4, KEY_NUM5, KEY_NUM6, KEY_NUM7, KEY_NUM8, KEY_NUM9, KEY_STAR, and KEY_POUND. (These key codes correspond to keys on a ITU-T standard telephone keypad.) The values defined for these key codes are all positive and the numberic values are equal to corresponding Unicode values, so (char)keyCode will produce the unicode character that corresponds to the key.

If the device include any other keys that have a unicode correspondence, the implementation should use the code as Unicode system does. Keys with no corresponding Unicode character, the implementation must use negative values. The actual values are implementation dependent, and applications that rely on these keycodes are not portable. Zero is defined to be an invalid key code.

It is sometimes useful to find the name of a key in order to display a message about this key. In this case the application may use the getKeyName() method to find a key's name.

Game actions

There are unique mappings from key codes to game actions and vice versa. The application can translate key codes to portable game actions with method getGameAction(int keyCode), and the key code corresponding to game action can be retrieved with getKeyCode(int gameAction). The implementation is not allowed to change the mapping of game actions and key codes during execution of the application.

In some devices the game actions UP, DOWN, LEFT and RIGHT may be mapped to 4-way navigation arrow keys. In this case, getGameAction(UP) would return a device-dependent code for the up-arrow key. Another possible mapping would be on the number keys 2, 4, 6 and 8. In this case, getGameAction(UP) would return KEY_NUM2. In both cases, an application interested on LEFT action, will receive a game action LEFT (the a key code mapped to LEFT) when user presses the key that is a "natural left" on her device.

The constant sets for game actions and keycodes are meant for different purposes. A portable game must either translate every key event to a game action with method getGameAction(int) or inquire the preferred keys in its initialization phase with the getKeyCode() method.

Commands

It is also possible for the user to issue commands when a canvas is current. Commands are mapped to keys and menus in a device-specific fashion. For some devices the keys used for commands may overlap with the keys that will deliver key code events to the canvas. If this is the case, the device will provide a means transparent to the application that enables the user to select a mode that determines whether these keys will deliver commands or key code events to the application. The set of key code events available to a canvas will not change depending upon the number of commands that are present on the canvas.

Event Delivery

The Canvas object defines several methods that are called by the implementation. These methods are primarily for the purpose of delivering events to the application, and so they are referred to as event delivery methods. The set of methods is:

These methods are all called serially. That is, the implementation will never call an event delivery method before a prior call to any of the event delivery methods has returned. (But see the note below.) This property enables applications to be assured that processing of a previous user event will have completed before the next event is delivered.

Calls to the call() method of Callable objects passed to Display.callSerially() will also be serialized along with calls to the event delivery methods. See callSerially() for further information.

Note: The serviceRepaints() method is an exception to this rule, as it blocks until paint() is called and returns. This will occur even if the application is in the midst of one of the event delivery methods and it calls serviceRepaints().

The key-related, pointer-related, and paint() methods will only be called while the canvas is current, that is, when it is actually displayed on the output device. These methods will be called on this Canvas object only after a call to showNotify() and before a call to hideNotify(). After hideNotify() has been called, none of the key, pointer, and paint methods will be called until after a subsequent call to showNotify() has returned. A call to a call() method resulting from callSerially() may occur irrespective of calls to showNotify() and hideNotify().

Whenever the Canvas is made current (when showNotify() is called) and when it actually becomes visible on the display, the paint() method will be called with a Graphics object whose clip region specifies the entire displayable area of the Canvas. Applications must not rely on any contents being preserved from a previous occasion when the Canvas was current.


Field Summary
static int DOWN
          Constant for the DOWN game action.
static int FIRE
          Constant for the FIRE game action.
static int GAME_A
          Constant for the general purpose "A" game action.
static int GAME_B
          Constant for the general purpose "B" game action.
static int GAME_C
          Constant for the general purpose "C" game action.
static int GAME_D
          Constant for the general purpose "D" game action.
static int KEY_NUM0
          Keycode for ITU-T key 0.
static int KEY_NUM1
          Keycode for ITU-T key 1.
static int KEY_NUM2
          Keycode for ITU-T key 2.
static int KEY_NUM3
          Keycode for ITU-T key 3.
static int KEY_NUM4
          Keycode for ITU-T key 4.
static int KEY_NUM5
          Keycode for ITU-T key 5.
static int KEY_NUM6
          Keycode for ITU-T key 6.
static int KEY_NUM7
          Keycode for ITU-T key 7.
static int KEY_NUM8
          Keycode for ITU-T key 8.
static int KEY_NUM9
          Keycode for ITU-T key 9.
static int KEY_POUND
          Keycode for ITU-T key "pound" (#).
static int KEY_STAR
          Keycode for ITU-T key "star"(*).
static int LEFT
          Constant for the LEFT game action.
static int RIGHT
          Constant for the RIGHT game action.
static int UP
          Constant for the UP game action.
 
Constructor Summary
protected Canvas()
          Constructs a new Canvas object.
 
Method Summary
 int getGameAction(int keyCode)
          Gets the game action associated with the given key code of the device.
 int getHeight()
          Gets height of the displayable area in pixels.
 int getKeyCode(int gameAction)
          Gets the key code that corresponds to the specified game action on the device.
 String getKeyName(int keycode)
           Gets an informative key string for a key.
 int getWidth()
          Gets width of the displayable area in pixels.
 boolean hasPointerEvents()
          Checks if the platform supports pointer press and release events.
 boolean hasPointerMotionEvents()
          * Checks if the platform supports pointer motion events (pointer dragged).
 boolean hasRepeatEvents()
          Checks if the platform can ganerate repeat events when key is kept down.
protected  void hideNotify()
          The implementation calls showNotify() when this Canvas is shown.
protected  void keyPressed(int keyCode)
          Called when a key is pressed.
protected  void keyReleased(int keyCode)
          Called when a key is released.
protected  void keyRepeated(int keyCode)
          Called when a key is repeated (held down).
protected abstract  void paint(Graphics g)
          Renders the Canvas.
protected  void pointerDragged(int x, int y)
          Called when the pointer is dragged.
protected  void pointerPressed(int x, int y)
          Called when the pointer is pressed.
protected  void pointerReleased(int x, int y)
          Called when the pointer is released.
 void repaint()
          Requests a repaint for the entire Canvas.
 void repaint(int x, int y, int width, int height)
           Requests a repaint for the specified region of the Screen.
 void serviceRepaints()
           Forces any pending repaint requests to be serviced immediately.
protected  void showNotify()
          The implementation calls showNotify() when this Canvas is shown.
 
Methods inherited from class javax.microedition.lcdui.Displayable
addCommand, isShown, removeCommand, setListener
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

UP

public static final int UP

Constant for the UP game action.

Constant value 1 is set to UP.


DOWN

public static final int DOWN
Constant for the DOWN game action.

Constant value 6 is set to DOWN.


LEFT

public static final int LEFT
Constant for the LEFT game action.

Constant value 2 is set to LEFT.


RIGHT

public static final int RIGHT
Constant for the RIGHT game action.

Constant value 5 is set to RIGHT.


FIRE

public static final int FIRE
Constant for the FIRE game action.

Constant value 8 is set to FIRE.


GAME_A

public static final int GAME_A
Constant for the general purpose "A" game action.

Constant value 9 is set to GAME_A.


GAME_B

public static final int GAME_B
Constant for the general purpose "B" game action.

Constant value 10 is set to GAME_B.


GAME_C

public static final int GAME_C
Constant for the general purpose "C" game action.

Constant value 12 is set to GAME_C.


GAME_D

public static final int GAME_D
Constant for the general purpose "D" game action.

Constant value 13 is set to GAME_D.


KEY_NUM0

public static final int KEY_NUM0
Keycode for ITU-T key 0.

Constant value 48 is set to KEY_NUM0.


KEY_NUM1

public static final int KEY_NUM1
Keycode for ITU-T key 1.

Constant value 49 is set to KEY_NUM1.


KEY_NUM2

public static final int KEY_NUM2
Keycode for ITU-T key 2.

Constant value 50 is set to KEY_NUM2.


KEY_NUM3

public static final int KEY_NUM3
Keycode for ITU-T key 3.

Constant value 51 is set to KEY_NUM3.


KEY_NUM4

public static final int KEY_NUM4
Keycode for ITU-T key 4.

Constant value 52 is set to KEY_NUM4.


KEY_NUM5

public static final int KEY_NUM5
Keycode for ITU-T key 5.

Constant value 53 is set to KEY_NUM5.


KEY_NUM6

public static final int KEY_NUM6
Keycode for ITU-T key 6.

Constant value 54 is set to KEY_NUM6.


KEY_NUM7

public static final int KEY_NUM7
Keycode for ITU-T key 7.

Constant value 55 is set to KEY_NUM7.


KEY_NUM8

public static final int KEY_NUM8
Keycode for ITU-T key 8.

Constant value 56 is set to KEY_NUM8.


KEY_NUM9

public static final int KEY_NUM9
Keycode for ITU-T key 9.

Constant value 57 is set to KEY_NUM09.


KEY_STAR

public static final int KEY_STAR
Keycode for ITU-T key "star"(*).

Constant value 42 is set to KEY_STAR.


KEY_POUND

public static final int KEY_POUND
Keycode for ITU-T key "pound" (#).

Constant value 35 is set to KEY_POUND.

Constructor Detail

Canvas

protected Canvas()
Constructs a new Canvas object.
Method Detail

getWidth

public int getWidth()
Gets width of the displayable area in pixels. The value is unchanged during the execution of the application and all Canvases will have the same value.
Returns:
width of the displayable area

getHeight

public int getHeight()
Gets height of the displayable area in pixels. The value is unchanged during the execution of the application and all Canvases will have the same value.
Returns:
height of the displayable area

hasPointerEvents

public boolean hasPointerEvents()
Checks if the platform supports pointer press and release events.
Returns:
true if the device supports pointer events

hasPointerMotionEvents

public boolean hasPointerMotionEvents()
* Checks if the platform supports pointer motion events (pointer dragged). Applications may use this method to determine if the platform is capable of supporting a game.
Returns:
true if the device supports pointer motion events

hasRepeatEvents

public boolean hasRepeatEvents()
Checks if the platform can ganerate repeat events when key is kept down.
Returns:
true if the device supports repeat events

getKeyCode

public int getKeyCode(int gameAction)
Gets the key code that corresponds to the specified game action on the device.

It is assumed that the mapping between concrete keys and abstract events does not change during the execution of the game.

Pre-conditions:
gameAction is a defined game action (Canvas.UP, Canvas.DOWN, Canvas.FIRE, etc.)
Post-conditions:
- The key code of the key that corresponds to the specified action is returned (or -1 if the game action is invalid or not supported by the device)
Parameters:
gameAction - The game action to obtain the key code for. (one of UP, DOWN, LEFT, RIGHT, GAME_A, GAME_B, GAME_C and GAME_D.)
Returns:
The key code.
Throws:
IllegalArgumentException - if the gameAction is not one of the defined game actions.

getKeyName

public String getKeyName(int keycode)

Gets an informative key string for a key. The string returned should resemble the text physically printed on the key. For example, on a device with function keys F1 through F4, calling this method on the keycode for the F1 key will return the string "F1". A typical use for this string will be to compose help text such as "Press F1 to proceed."

There is no direct mapping from game actions to key names. To get the string name for a game action, the application must call

getKeyName(getKeyCode(GAME_A))

Parameters:
keycode - the key code being requested
Returns:
a string name for the key, or null if no name is available

getGameAction

public int getGameAction(int keyCode)
Gets the game action associated with the given key code of the device.

It is assumed that the mapping between concrete keys and abstract events does not change during the execution of the game.

Pre-conditions:
- keyCode refers to a key that is mapped as a game key on the device
Post-conditions:
- The game action of the key is returned (or 0 if the key is not mapped to a game action or not present on the device)
Parameters:
keyCode - The key code
Returns:
The corresponding game action (UP, DOWN, LEFT, RIGHT, GAME_A, etc.) or 0 if the keyCode does not represent any game action.

keyPressed

protected void keyPressed(int keyCode)

Called when a key is pressed. The key is one of the KEY_... codes defined in above.

The getGameAction() method can be called to determine what game action, if any, is mapped to the key. Class Canvas has an empty implementation of this method, and the subclass has to redefine it if it wants to listen this method.

Parameters:
keyCode - The key code of the key that was pressed.

keyRepeated

protected void keyRepeated(int keyCode)
Called when a key is repeated (held down). The getGameAction() method can be called to determine what game action, if any, is mapped to the key. Class Canvas has an empty implementation of this method, and the subclass has to redefine it if it wants to listen this method.
Parameters:
keyCode - The key code of the key that was repeated
See Also:
hasRepeatEvents()

keyReleased

protected void keyReleased(int keyCode)
Called when a key is released. The getGameAction() method can be called to determine what game action, if any, is mapped to the key. Class Canvas has an empty implementation of this method, and the subclass has to redefine it if it wants to listen this method.
Parameters:
keyCode - The key code of the key that was released

pointerPressed

protected void pointerPressed(int x,
                              int y)
Called when the pointer is pressed. The hasPointerEvents() method may be called to determine if the device supports pointer events. Class Canvas has an empty implementation of this method, and the subclass has to redefine it if it wants to listen this method.
Parameters:
x - The horizontal location where the pointer was pressed (relative to the Canvas)
y - The vertical location where the pointer was pressed (relative to the Canvas)

pointerReleased

protected void pointerReleased(int x,
                               int y)
Called when the pointer is released. The hasPointerEvents() method may be called to determine if the device supports pointer events. Class Canvas has an empty implementation of this method, and the subclass has to redefine it if it wants to listen this method.
Parameters:
x - The horizontal location where the pointer was released (relative to the Canvas)
y - The vertical location where the pointer was released (relative to the Canvas)

pointerDragged

protected void pointerDragged(int x,
                              int y)
Called when the pointer is dragged. The hasPointerMotionEvents() method may be called to determine if the device supports pointer events. Class Canvas has an empty implementation of this method, and the subclass has to redefine it if it wants to listen this method.
Parameters:
x - The horizontal location where the pointer was dragged (relative to the Canvas)
y - The vertical location where the pointer was dragged (relative to the Canvas)

repaint

public final void repaint(int x,
                          int y,
                          int width,
                          int height)

Requests a repaint for the specified region of the Screen. Calling this method may result in subsequent call to paint(), where the passed Graphics object's clip region will include at least the specified region.

If the canvas is not visible, or if width and height are zero or less, or if the rectangle does not specify a visible region of the display, this call has no effect.

The call to paint() occurs independently of the call to repaint(). That is, repaint() will not block waiting for paint() to finish. The paint() method will either be called after the caller of repaint() returns to the implementation (if the caller is a callback) or on another thread entirely.

To synchronize with its paint() routine, applications can use either Display.callSerially() or serviceRepaints(), or they can code explicit synchronization into their paint() routine.

The origin of the coordinate system is above and to the left of the pixel in the upper left corner of the displayable area of the Canvas. The X-coordinate is positive right and the Y-coordinate is positive downwards.

Parameters:
x - the x coordinate of the rectangle to be repainted
y - the y coordinate of the rectangle to be repainted
width - the width of the rectangle to be repainted
height - the height of the rectangle to be repainted
See Also:
Display.callSerially(Callable), serviceRepaints()

repaint

public final void repaint()
Requests a repaint for the entire Canvas. The effect is identical to

repaint(0, 0, getWidth(), getHeight());


serviceRepaints

public final void serviceRepaints()

Forces any pending repaint requests to be serviced immediately. This method blocks until the pending requests have been serviced. If there are no pending repaints, or if this canvas is not currently on the display, this call does nothing and returns immediately.

WARNING: This method blocks until the call to the application's paint() method returns. The application has no control over which thread calls paint(); it may vary from implementation to implementation. If the caller of serviceRepaints() holds a lock that the paint() method acquires, this may result in deadlock. Therefore, callers of serviceRepaints() must not hold any locks that might be acquired within the paint() method. The Display.callSerially() method provides a facility where an application can be called back after painting has completed, instead of issuing a blocking method call.

See Also:
Display.callSerially(Callable)

showNotify

protected void showNotify()
The implementation calls showNotify() when this Canvas is shown. Canvas sub-classes may override this method to perform tasks immediately before being shown such as initializing data, starting timers, etc. Class Canvas has an empty implementation of this method, and the subclass has to redefine it if it wants to listen this method.

hideNotify

protected void hideNotify()
The implementation calls showNotify() when this Canvas is shown. Canvas sub-classes may override this method to perform tasks immediately after being hidden such as freeing resources, terminating threads or timers, etc. Class Canvas has an empty implementation of this method, and the subclass has to redefine it if it wants to listen this method.

paint

protected abstract void paint(Graphics g)
Renders the Canvas. The application must implement this method in order to paint any graphics.

The Graphics object's clip region defines the area of the screen that is considered to be invalid. A correctly-written paint() routine must paint every pixel within this region. Applications must not assume that they know the underlying source of the paint() call and use this assumption to paint only a subset of the pixels within the clip region. The reason is that this particular paint() call may have resulted from multiple repaint() requests, some of which may have been generated from outside the application. An application that paints only what it thinks is necessary to be painted may display incorrectly if the screen contents had been invalidated by, for example, an incoming telephone call.

Operations on this graphics object after the paint() call returns are undefined. The application is thus must not to cache this Graphics object for later use or use by another thread. It must only be used within the scope of this method.

The implementation may postpone visible effects of graphics operations until the end of the paint method.

The contents of the Canvas are never saved if the Canvas is made not current and then is made current again. Thus, a paint() call with a clip region of the entire Canvas will always occur some time after showNotify() is called, if the Canvas is actually on the display. (The Canvas may not be on the display if this MIDlet is in the background.) Application whose repaint recomputation is expensive may create an offscreen Image, paint into it, and then draw this image on the Canvas when paint() is called.

Pre-conditions:
- The Graphics object's clip region includes at least one pixel within this Canvas
- The Graphics object's color is set to black
- The Font is set to the default font that is obtained by calling Font.getDefaultFont()
- The origin of the coordinate system is located at the upper-left corner of the Canvas
- The Canvas is current, i.e., showNotify() has been called and hideNotify() has not yet been called.
Post-conditions:
- The Canvas has rendered itself
- No references to the Graphics object are maintained by the Canvas
Parameters:
g - the Graphics object to render the Canvas with.

MID Profile

Submit a comment or suggestion Version 0.9 of MID Profile Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries. Copyright 1993-2000 Sun Microsystems, Inc. 901 San Antonio Road,Palo Alto, California, 94303, U.S.A. All Rights Reserved.