File	Doc	Category	Size	Date	Package
Canvas.java	API Doc	J2ME MIDP 2.0	46300	Thu Nov 07 12:02:26 GMT 2002	javax.microedition.lcdui

Canvas

• java.lang.Object
  • Displayable

if (keyCode > 0) {
char ch = (char)keyCode;
// ...
} 

g == getGameAction(getKeyCode(g)) // (1)
k == getKeyCode(getGameAction(k)) // (2) 

Fields Summary
public static final int	UP Constant for the UP game action. Constant value 1 is set to UP.
public static final int	DOWN Constant for the DOWN game action. Constant value 6 is set to DOWN.
public static final int	LEFT Constant for the LEFT game action. Constant value 2 is set to LEFT.
public static final int	RIGHT Constant for the RIGHT game action. Constant value 5 is set to RIGHT.
public static final int	FIRE Constant for the FIRE game action. Constant value 8 is set to FIRE.
public static final int	GAME_A Constant for the general purpose "A" game action. Constant value 9 is set to GAME_A.
public static final int	GAME_B Constant for the general purpose "B" game action. Constant value 10 is set to GAME_B.
public static final int	GAME_C Constant for the general purpose "C" game action. Constant value 11 is set to GAME_C.
public static final int	GAME_D Constant for the general purpose "D" game action. Constant value 12 is set to GAME_D.
public static final int	KEY_NUM0 keyCode for ITU-T key 0. Constant value 48 is set to KEY_NUM0.
public static final int	KEY_NUM1 keyCode for ITU-T key 1. Constant value 49 is set to KEY_NUM1.
public static final int	KEY_NUM2 keyCode for ITU-T key 2. Constant value 50 is set to KEY_NUM2.
public static final int	KEY_NUM3 keyCode for ITU-T key 3. Constant value 51 is set to KEY_NUM3.
public static final int	KEY_NUM4 keyCode for ITU-T key 4. Constant value 52 is set to KEY_NUM4.
public static final int	KEY_NUM5 keyCode for ITU-T key 5. Constant value 53 is set to KEY_NUM5.
public static final int	KEY_NUM6 keyCode for ITU-T key 6. Constant value 54 is set to KEY_NUM6.
public static final int	KEY_NUM7 keyCode for ITU-T key 7. Constant value 55 is set to KEY_NUM7.
public static final int	KEY_NUM8 keyCode for ITU-T key 8. Constant value 56 is set to KEY_NUM8.
public static final int	KEY_NUM9 keyCode for ITU-T key 9. Constant value 57 is set to KEY_NUM09.
public static final int	KEY_STAR keyCode for ITU-T key "star" (*). Constant value 42 is set to KEY_STAR.
public static final int	KEY_POUND keyCode for ITU-T key "pound" (#). Constant value 35 is set to KEY_POUND.
private boolean	suppressKeyEvents Used by GameCanvas to suppress Game action key events

Constructors Summary
protected Canvas() Constructs a new Canvas object.

Methods Summary
private boolean	allowKey(int keyCode) Test to see if the given keyCode should be sent to the application param keyCode the key code to pass to the application return true if the key should be allowed if (!suppressKeyEvents) { return true; } // NOTE: we're using Canvas's public getGameAction() // method here switch (getGameAction(keyCode)) { case Canvas.UP: case Canvas.DOWN: case Canvas.LEFT: case Canvas.RIGHT: case Canvas.FIRE: case Canvas.GAME_A: case Canvas.GAME_B: case Canvas.GAME_C: case Canvas.GAME_D : // don't generate key events for // the defined game keys return false; default: return true; }
void	callHideNotify(Display d) Notify this Canvas it is being hidden on the given Display param d the Display the Canvas is being hidden on synchronized (Display.calloutLock) { try { this.hideNotify(); } catch (Throwable t) { Display.handleThrowable(t); } }
void	callKeyPressed(int keyCode) Handle a key press param keyCode The key that was pressed if (allowKey(keyCode)) { synchronized (Display.calloutLock) { try { this.keyPressed(keyCode); } catch (Throwable t) { Display.handleThrowable(t); } } }
void	callKeyReleased(int keyCode) Handle a key release param keyCode The key that was released if (allowKey(keyCode)) { synchronized (Display.calloutLock) { try { this.keyReleased(keyCode); } catch (Throwable t) { Display.handleThrowable(t); } } }
void	callKeyRepeated(int keyCode) Handle a repeated key press param keyCode The key that was pressed if (allowKey(keyCode)) { synchronized (Display.calloutLock) { try { this.keyRepeated(keyCode); } catch (Throwable t) { Display.handleThrowable(t); } } }
void	callPaint(Graphics g, java.lang.Object target) Paint this Canvas param g the Graphics to paint to param target the target Object of this repaint super.callPaint(g, target); if (g.getClipY() + g.getClipHeight() <= viewport[Y]) { return; } // We prevent the Canvas from drawing outside of the // allowable viewport - such as over the command labels g.clipRect(viewport[X], viewport[Y], viewport[WIDTH], viewport[HEIGHT]); synchronized (Display.calloutLock) { g.translate(viewport[X], viewport[Y]); try { paint(g); } catch (Throwable t) { Display.handleThrowable(t); } g.translate(-viewport[X], -viewport[Y]); }
void	callPointerDragged(int x, int y) Handle a pointer drag event param x The x coordinate of the drag param y The y coordinate of the drag synchronized (Display.calloutLock) { try { this.pointerDragged(x - viewport[X], y - viewport[Y]); } catch (Throwable t) { Display.handleThrowable(t); } }
void	callPointerPressed(int x, int y) Handle a pointer press event param x The x coordinate of the press param y The y coordinate of the press synchronized (Display.calloutLock) { try { this.pointerPressed(x - viewport[X], y - viewport[Y]); } catch (Throwable t) { Display.handleThrowable(t); } }
void	callPointerReleased(int x, int y) Handle a pointer release event param x The x coordinate of the release param y The y coordinate of the release synchronized (Display.calloutLock) { try { this.pointerReleased(x - viewport[X], y - viewport[Y]); } catch (Throwable t) { Display.handleThrowable(t); } }
void	callShowNotify(Display d) Notify this Canvas it is being shown on the given Display param d the Display the Canvas is being shown on super.callShowNotify(d); super.layout(); synchronized (Display.calloutLock) { try { this.showNotify(); } catch (Throwable t) { Display.handleThrowable(t); } }
void	callSizeChanged(int w, int h) Handle a size change notification. param w the new width of this Canvas param h the new height of this Canvas super.callSizeChanged(w, h); /* * sizeChangeOccurred is a boolean which (when true) indicates * that sizeChanged() will be called at a later time. So, if it * is false after calling super(), we go ahead and notify the * Canvas now, rather than later */ if (!super.sizeChangeOccurred) { synchronized (Display.calloutLock) { try { this.sizeChanged(w, h); } catch (Throwable t) { Display.handleThrowable(t); } } }
public int	getGameAction(int keyCode) Gets the game action associated with the given key code of the device. Returns zero if no game action is associated with this key code. See above for further discussion of game actions. The mapping between key codes and game actions will not change during the execution of the application. param keyCode the key code return the game action corresponding to this key, or 0 if none throws IllegalArgumentException if keyCode is not a valid key code // SYNC NOTE: no locking necessary as we are doing a static // table lookup and getGameAction() is implemented natively int n = Display.getGameAction(keyCode); if (n == -1) { throw new IllegalArgumentException(); } return n;
public int	getKeyCode(int gameAction) Gets a key code that corresponds to the specified game action on the device. The implementation is required to provide a mapping for every game action, so this method will always return a valid key code for every game action. See above for further discussion of game actions. There may be multiple keys associated with the same game action; however, this method will return only one of them. Applications should translate the key code of every key event into a game action using {@link #getGameAction} and then interpret the resulting game action, instead of generating a table of key codes at using this method during initialization. The mapping between key codes and game actions will not change during the execution of the application. param gameAction the game action return a key code corresponding to this game action throws IllegalArgumentException if gameAction is not a valid game action // SYNC NOTE: no locking necessary as we are doing a static // table lookup and getKeyCode() is implemented natively int n = Display.getKeyCode(gameAction); if (n == 0) { throw new IllegalArgumentException(); } return n;
public java.lang.String	getKeyName(int keyCode) Gets an informative key string for a key. The string returned will resemble the text physically printed on the key. This string is suitable for displaying to the user. 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." This method will return a non-empty string for every valid key code. There is no direct mapping from game actions to key names. To get the string name for a game action GAME_A, the application must call getKeyName(getKeyCode(GAME_A)); param keyCode the key code being requested return a string name for the key throws IllegalArgumentException if keyCode is not a valid key code // SYNC NOTE: no locking necessary as we are doing a static // table lookup and getKeyName() is implemented natively String s = Display.getKeyName(keyCode); if (s == null) { throw new IllegalArgumentException(); } return s;
public boolean	hasPointerEvents() Checks if the platform supports pointer press and release events. return true if the device supports pointer events // SYNC NOTE: return of atomic value, no locking necessary return Display.POINTER_SUPPORTED;
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 motion events. return true if the device supports pointer motion events // SYNC NOTE: return of atomic value, no locking necessary return Display.MOTION_SUPPORTED;
public boolean	hasRepeatEvents() Checks if the platform can generate repeat events when key is kept down. return true if the device supports repeat events // SYNC NOTE: return of atomic value, no locking necessary return Display.REPEAT_SUPPORTED;
protected void	hideNotify() The implementation calls hideNotify() shortly after the Canvas has been removed from the display. Canvas subclasses may override this method in order to pause animations, revoke timers, etc. The default implementation of this method in class Canvas is empty.
public boolean	isDoubleBuffered() Checks if the Canvas is double buffered by the implementation. return true if double buffered, false otherwise // SYNC NOTE: return of atomic value, no locking necessary return Display.IS_DOUBLE_BUFFERED;
protected void	keyPressed(int keyCode) Called when a key is pressed. 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. param keyCode the key code of the key that was pressed
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. param keyCode the key code of the key that was released
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. param keyCode the key code of the key that was repeated see #hasRepeatEvents()
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. This is necessary because the implementation is not required to clear the region prior to calling paint() on it. Thus, failing to paint every pixel may result in a portion of the previous screen image remaining visible. 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. Thus, the application must not 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 it is hidden and then is made visible again. Thus, shortly after showNotify() is called, paint() will always 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. This call to paint() will not necessarily occur before any other key or pointer methods are called on the Canvas. Applications 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. The application code must never call paint(); it is called only by the implementation. The Graphics object passed to the paint() method has the following properties: the destination is the actual display, or if double buffering is in effect, a back buffer for the display; the clip region includes at least one pixel within this Canvas; the current color is black; the font is the same as the font returned by {@link Font#getDefaultFont() Font.getDefaultFont()}; the stroke style is {@link Graphics#SOLID SOLID}; the origin of the coordinate system is located at the upper-left corner of the Canvas; and the Canvas is visible, that is, a call to isShown() will return true. param g the Graphics object to be used for rendering the Canvas
protected void	pointerDragged(int x, int y) Called when the pointer is dragged. The {@link #hasPointerMotionEvents() 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. param x the horizontal location where the pointer was dragged (relative to the Canvas) param y the vertical location where the pointer was dragged (relative to the Canvas)
protected void	pointerPressed(int x, int y) Called when the pointer is pressed. The {@link #hasPointerEvents() 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. param x the horizontal location where the pointer was pressed (relative to the Canvas) param y the vertical location where the pointer was pressed (relative to the Canvas)
protected void	pointerReleased(int x, int y) Called when the pointer is released. The {@link #hasPointerEvents() 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. param x the horizontal location where the pointer was released (relative to the Canvas) param y the vertical location where the pointer was released (relative to the Canvas)
public final void	repaint(int x, int y, int width, int height) Requests a repaint for the specified region of the Canvas. 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 asynchronously 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 {@link Display#callSerially(Runnable) Display.callSerially()} or {@link #serviceRepaints() 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. param x the x coordinate of the rectangle to be repainted param y the y coordinate of the rectangle to be repainted param width the width of the rectangle to be repainted param height the height of the rectangle to be repainted see Display#callSerially(Runnable) see #serviceRepaints() synchronized (Display.LCDUILock) { callRepaint(x + viewport[X], y + viewport[Y], width, height, null); }
public final void	repaint() Requests a repaint for the entire Canvas. The effect is identical to repaint(0, 0, getWidth(), getHeight()); synchronized (Display.LCDUILock) { callRepaint(viewport[X], viewport[Y], viewport[WIDTH], viewport[HEIGHT], null); }
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 visible 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 {@link Display#callSerially(Runnable) Display.callSerially()} method provides a facility where an application can be called back after painting has completed, avoiding the danger of deadlock. see Display#callSerially(Runnable) // SYNC NOTE: unlike most public API methods, no locking is done // here. This is necessary because Display.serviceRepaints() // needs to handle its own locking. We avoid locking by making // a copy of currentDisplay -- an atomic operation -- before // testing and using it. Display d = currentDisplay; if (d != null) { d.serviceRepaints(this); }
public void	setFullScreenMode(boolean mode) Controls whether the Canvas is in full-screen mode or in normal mode. param mode true if the Canvas is to be in full screen mode, false otherwise since MIDP 2.0 if (mode == super.fullScreenMode) { return; } super.grabFullScreen(mode); synchronized (Display.LCDUILock) { super.fullScreenMode(mode); }
protected void	showNotify() The implementation calls showNotify() immediately prior to this Canvas being made visible on the display. Canvas subclasses may override this method to perform tasks before being shown, such as setting up animations, starting timers, etc. The default implementation of this method in class Canvas is empty.
protected void	sizeChanged(int w, int h) Called when the drawable area of the Canvas has been changed. This method has augmented semantics compared to {@link Displayable#sizeChanged(int, int) Displayable.sizeChanged}. In addition to the causes listed in Displayable.sizeChanged, a size change can occur on a Canvas because of a change between normal and full-screen modes. If the size of a Canvas changes while it is actually visible on the display, it may trigger an automatic repaint request. If this occurs, the call to sizeChanged will occur prior to the call to paint. If the Canvas has become smaller, the implementation may choose not to trigger a repaint request if the remaining contents of the Canvas have been preserved. Similarly, if the Canvas has become larger, the implementation may choose to trigger a repaint only for the new region. In both cases, the preserved contents must remain stationary with respect to the origin of the Canvas. If the size change is significant to the contents of the Canvas, the application must explicitly issue a repaint request for the changed areas. Note that the application's repaint request should not cause multiple repaints, since it can be coalesced with repaint requests that are already pending. If the size of a Canvas changes while it is not visible, the implementation may choose to delay calls to sizeChanged until immediately prior to the call to showNotify. In that case, there will be only one call to sizeChanged, regardless of the number of size changes. An application that is sensitive to size changes can update instance variables in its implementation of sizeChanged. These updated values will be available to the code in the showNotify, hideNotify, and paint methods. param w the new width in pixels of the drawable area of the Canvas param h the new height in pixels of the drawable area of the Canvas since MIDP 2.0 // this method is intended to be overridden by the application