Canvas (Mobile Information Device Profile 3.0)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

MIDP3.0

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

javax.microedition.lcdui
Class Canvas

java.lang.Object
  javax.microedition.lcdui.Displayable
      javax.microedition.lcdui.Canvas

Direct Known Subclasses:: GameCanvas

public abstract class Canvas
extends Displayable
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 actions, key events, and pointer events (if supported by the device). Methods are also provided to identify the device's capabilities and mapping of keys to actions. The key events are reported with respect to key codes, which are directly bound to concrete keys on the device, use of which may hinder portability. Portable applications should use actions instead of key codes.

Like other subclasses of Displayable, the Canvas class allows the application to register a listener for commands. Unlike other Displayables, however, 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.

CanvasItem subclasses, such as a TextEditor, may be drawn on Canvas or CustomItem. See CanvasItem and TextEditor for more details.

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.) Other keys may be present on the keyboard, and they will generally have key codes distinct from those list above. In order to guarantee portability, applications should use only the standard key codes.

The standard key codes' values are equal to the Unicode encoding for the character that represents the key. If the device includes any other keys that have an obvious correspondence to a Unicode character, their key code values should equal the Unicode encoding for that character. For keys that have no corresponding Unicode character, the implementation must use negative values. Zero is defined to be an invalid key code. It is thus possible for an application to convert a keyCode into a Unicode character using the following code:


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

This technique is useful only in certain limited cases. In particular, it is not sufficient for full textual input, because it does not handle upper and lower case, keyboard shift states, and characters that require more than one keystroke to enter. For textual input, applications should always use TextBox or TextField objects.

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.

Actions (aka Game Actions)

Portable applications that need soft key and arrow events and action-related events should use actions in preference to key codes and key names. Soft key codes are mapped to actions defined by exact placement values as specified for the Exact placement of Commands. Navigation and game keys are mapped to the actions: UP, DOWN, LEFT, RIGHT, FIRE, GAME_A, GAME_B, GAME_C, and GAME_D.

Each key code may be mapped to at most one action. However, an action may be associated with more than one key code. The application can translate a key code into an action using the getGameAction(int keyCode) method, and it can translate an action into a key code using the getKeyCode(int gameAction) method. There may be multiple keycodes associated with a particular action, but getKeyCode returns only one of them. Supposing that g is a valid action and k is a valid key code for a key associated with a action, consider the following expressions:

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

Expression (1) is always true. However, expression (2) might be true but is not necessarily true.

Portable applications that are interested in using actions should translate every key event into an action by calling the getGameAction() method and then testing the result. For example, on some devices the actions UP, DOWN, LEFT and RIGHT may be mapped to 4-way navigation arrow keys. In this case,getKeyCode(UP) would return a device-dependent code for the up-arrow key. On other devices, a possible mapping would be on the number keys 2, 4, 6 and 8. In this case, getKeyCode(UP) would return KEY_NUM2. In both cases, the getGameAction() method would return the LEFT action when the user presses the key that is a "natural left" on her device.

The implementation is not allowed to change the mapping of actions and key codes during execution of the application. However, if the device keypad can be used in different modes, and some modes restrict user access to certain keys, or if the device has several different keypads that are not meant to used simultaneously, a mobile handset implementation is NOT REQUIRED to ensure that the mapping between key codes and action does not change during the execution of the application. Consequently, applications should use the getGameAction() method to determine which action is associated with a given key code. It is recommended that applications avoid using the getKeyCode() method to determine which key is assigned to a specific action.

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. When the Canvas is in normal mode (see below), the set of key code events available to a canvas will not change depending upon the number of commands present or the presence of a command listener. When the Canvas is in full-screen mode, if there is no command listener present, the device MUST deliver key code events for keys that would otherwise be reserved for delivery of commands. Game developers should be aware that access to commands will vary greatly across devices, and that requiring the user to issue commands during game play may have a great impact on the ease with which the game can be played.

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:

showNotify()
hideNotify()
keyPressed()
keyRepeated()
keyReleased()
pointerPressed()
pointerDragged()
pointerReleased()
paint()

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. 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 when it calls serviceRepaints().

The Display.callSerially() method can be used to serialize some application-defined work with the event stream. For further information, see the Event Handling and Concurrency sections of the package summary.

The key-related, pointer-related, and paint() methods will only be called while the Canvas is actually visible on the output device. These methods will therefore only 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 run() method resulting from callSerially() may occur irrespective of calls to showNotify() and hideNotify().

The showNotify() method is called prior to the Canvas actually being made visible on the display, and the hideNotify() method is called after the Canvas has been removed from the display. The visibility state of a Canvas (or any other Displayable object) may be queried through the use of the Displayable.isShown() method. The change in visibility state of a Canvas may be caused by the application management software moving MIDlets between foreground and background states, or by the system obscuring the Canvas with system screens. Thus, the calls to showNotify() and hideNotify() are not under the control of the MIDlet and may occur fairly frequently. Application developers are encouraged to perform expensive setup and teardown tasks outside the showNotify() and hideNotify() methods in order to make them as lightweight as possible.

A Canvas can be in normal mode or in full-screen mode. In normal mode, space on the display may be occupied by command labels, a title, and a ticker. By setting a Canvas into full-screen mode, the application is requesting that the Canvas occupy as much of the display space as is possible. In full-screen mode, the title and ticker are not displayed even if they are present on the Canvas, and Commands may be presented using some alternative means (such as through a pop-up menu). Note that the implementation may still consume a portion of the display for things like status indicators, even if the displayed Canvas is in full-screen mode. In full-screen mode, although the title is not displayed, its text may still be used for other purposes, such as for the title of a pop-up menu of Commands.

Canvas objects are in normal mode by default. The normal vs. full-screen mode setting is controlled through the use of the setFullScreenMode(boolean) method.

Calling setFullScreenMode(boolean) may result in sizeChanged() being called. The default implementation of this method does nothing. The application can override this method to handle changes in size of available drawing area.

Note: As mentioned in the "Specification Requirements" section of the overview, implementations must provide the user with an indication of network usage. If the indicator is rendered on screen, it must be visible when network activity occurs, even when the Canvas is in full-screen mode.

Since:: MIDP 1.0

Field Summary
`static int`	`ACTIONS_ALL` Constant for requesting the full set of actions comprised of UP, DOWN, LEFT, RIGHT, FIRE, GAME_A, GAME_B, GAME_C, and GAME_D.
`static int`	`ACTIONS_NAVIGATION` Constant for requesting the basic set of actions comprised of UP, DOWN, LEFT, RIGHT, and FIRE ACTIONS_NAVIGATION has a value of -1.
`static int`	`ACTIONS_NONE` Constant for requesting the empty set of actions ACTIONS_NONE has a value of 0.
`static int`	`DOWN` Constant for the `DOWN` action.
`static int`	`FIRE` Constant for the `FIRE` action.
`static int`	`GAME_A` Constant for the general purpose "`A`" action.
`static int`	`GAME_B` Constant for the general purpose "`B`" action.
`static int`	`GAME_C` Constant for the general purpose "`C`" action.
`static int`	`GAME_D` Constant for the general purpose "`D`" action.
`static int`	`KEY_BACKSPACE` keyCode for the backspace key, U+0008 BACKSPACE.
`static int`	`KEY_DELETE` keyCode for the delete key, U+007F DELETE.
`static int`	`KEY_DOWN` keyCode for the down key.
`static int`	`KEY_ENTER` keyCode for the enter key, U+000A LINE FEED.
`static int`	`KEY_ESCAPE` keyCode for the escape key, U+001B ESCAPE.
`static int`	`KEY_LEFT` keyCode for the left key.
`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_RIGHT` keyCode for the right key.
`static int`	`KEY_SELECT` keyCode for the select key.
`static int`	`KEY_SPACE` keyCode for the space key, U+0020 SPACE.
`static int`	`KEY_STAR` keyCode for ITU-T key "star" (`*`).
`static int`	`KEY_TAB` keyCode for the tabulation key, U+0009 HORIZONTAL TABULATION.
`static int`	`KEY_UP` keyCode for the up key.
`static int`	`LEFT` Constant for the `LEFT` action.
`static int`	`RIGHT` Constant for the `RIGHT` action.
`static int`	`UP` Constant for the `UP` action.

Constructor Summary
`protected`	`Canvas()` Constructs a new `Canvas` object

Method Summary
`int`	`getGameAction(int keyCode)` Gets the action associated with the given key code of the device.
`int`	`getHeight()` Gets the height in pixels of the displayable area of the `Canvas`.
`int`	`getKeyCode(int action)` Gets a key code that corresponds to the specified action on the device.
`java.lang.String`	`getKeyName(int keyCode)` Gets an informative key string for a key.
`int[]`	`getSoftkeyLabelCoordinates(int placement)` Gets the upper-left coordinates on the Canvas coordinate system, width, and height of the given placement.
`int`	`getWidth()` Gets the width in pixels of the displayable area of the `Canvas`.
`boolean`	`hasPointerEvents()` Deprecated. Support for pointer press and release events are determined by the `Display` . Use `Display.hasPointerevents()`
`boolean`	`hasPointerMotionEvents()` Deprecated. Support for pointer motion events are determined by the `Display` . Use `Display.hasPointerMotionevents()`
`boolean`	`hasRepeatEvents()` Checks if the platform can generate repeat events when key is kept down.
`protected void`	`hideNotify()` The implementation calls `hideNotify()` shortly after the `Canvas` has been removed from the display.
`boolean`	`isDoubleBuffered()` Checks if the `Canvas` is double buffered by the implementation.
`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 `Canvas`.
`void`	`serviceRepaints()` Forces any pending repaint requests to be serviced immediately.
`void`	`setFullScreenMode(boolean mode)` Controls whether the `Canvas` is in full-screen mode or in normal mode.
`void`	`setKeyListener(KeyListener listener)` Sets a key listener for key events to this Canvas, replacing any previous KeyListener.
`void`	`setPaintMode(boolean opaque)` Sets the paint mode for this Canvas.
`void`	`setRequiredActions(int actionSet)` Specifies the set of actions that must be available on touch screen devices while this Canvas is current on the foreground Display.
`protected void`	`showNotify()` The implementation calls `showNotify()` immediately prior to this `Canvas` being made visible on the display.
`protected void`	`sizeChanged(int w, int h)` Called when the drawable area of the `Canvas` has been changed.

Methods inherited from class javax.microedition.lcdui.Displayable
`addCommand, getCommand, getCommandLayoutPolicy, getCommands, getCurrentDisplay, getMenu, getTicker, getTitle, invalidateCommandLayout, isShown, removeCommand, removeCommandOrMenu, setCommand, setCommandLayoutPolicy, setCommandListener, setMenu, setTicker, setTitle`

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 action.

Constant value 1 is set to UP.

See Also:: Constant Field Values

DOWN

public static final int DOWN

Constant for the DOWN action.

Constant value 6 is set to DOWN.

See Also:: Constant Field Values

LEFT

public static final int LEFT

Constant for the LEFT action.

Constant value 2 is set to LEFT.

See Also:: Constant Field Values

RIGHT

public static final int RIGHT

Constant for the RIGHT action.

Constant value 5 is set to RIGHT.

See Also:: Constant Field Values

FIRE

public static final int FIRE

Constant for the FIRE action.

Constant value 8 is set to FIRE.

See Also:: Constant Field Values

GAME_A

public static final int GAME_A

Constant for the general purpose "A" action.

Constant value 9 is set to GAME_A.

See Also:: Constant Field Values

GAME_B

public static final int GAME_B

Constant for the general purpose "B" action.

Constant value 10 is set to GAME_B.

See Also:: Constant Field Values

GAME_C

public static final int GAME_C

Constant for the general purpose "C" action.

Constant value 11 is set to GAME_C.

See Also:: Constant Field Values

GAME_D

public static final int GAME_D

Constant for the general purpose "D" action.

Constant value 12 is set to GAME_D.

See Also:: Constant Field Values

KEY_NUM0

public static final int KEY_NUM0

keyCode for ITU-T key 0.

Constant value 48 is set to KEY_NUM0.

See Also:: Constant Field Values

KEY_NUM1

public static final int KEY_NUM1

keyCode for ITU-T key 1.

Constant value 49 is set to KEY_NUM1.

See Also:: Constant Field Values

KEY_NUM2

public static final int KEY_NUM2

keyCode for ITU-T key 2.

Constant value 50 is set to KEY_NUM2.

See Also:: Constant Field Values

KEY_NUM3

public static final int KEY_NUM3

keyCode for ITU-T key 3.

Constant value 51 is set to KEY_NUM3.

See Also:: Constant Field Values

KEY_NUM4

public static final int KEY_NUM4

keyCode for ITU-T key 4.

Constant value 52 is set to KEY_NUM4.

See Also:: Constant Field Values

KEY_NUM5

public static final int KEY_NUM5

keyCode for ITU-T key 5.

Constant value 53 is set to KEY_NUM5.

See Also:: Constant Field Values

KEY_NUM6

public static final int KEY_NUM6

keyCode for ITU-T key 6.

Constant value 54 is set to KEY_NUM6.

See Also:: Constant Field Values

KEY_NUM7

public static final int KEY_NUM7

keyCode for ITU-T key 7.

Constant value 55 is set to KEY_NUM7.

See Also:: Constant Field Values

KEY_NUM8

public static final int KEY_NUM8

keyCode for ITU-T key 8.

Constant value 56 is set to KEY_NUM8.

See Also:: Constant Field Values

KEY_NUM9

public static final int KEY_NUM9

keyCode for ITU-T key 9.

Constant value 57 is set to KEY_NUM09.

See Also:: Constant Field Values

KEY_STAR

public static final int KEY_STAR

keyCode for ITU-T key "star" (*).

Constant value 42 is set to KEY_STAR.

See Also:: Constant Field Values

KEY_POUND

public static final int KEY_POUND

keyCode for ITU-T key "pound" (#).

Constant value 35 is set to KEY_POUND.

See Also:: Constant Field Values

KEY_UP

public static final int KEY_UP

keyCode for the up key.

Constant value -1 is set to KEY_UP.

See Also:: Constant Field Values

KEY_DOWN

public static final int KEY_DOWN

keyCode for the down key.

Constant value -2 is set to KEY_DOWN.

See Also:: Constant Field Values

KEY_LEFT

public static final int KEY_LEFT

keyCode for the left key.

Constant value -3 is set to KEY_LEFT.

See Also:: Constant Field Values

KEY_RIGHT

public static final int KEY_RIGHT

keyCode for the right key.

Constant value -4 is set to KEY_RIGHT.

See Also:: Constant Field Values

KEY_SELECT

public static final int KEY_SELECT

keyCode for the select key.

Constant value -5 is set to KEY_SELECT.

See Also:: Constant Field Values

KEY_ENTER

public static final int KEY_ENTER

keyCode for the enter key, U+000A LINE FEED.

Constant value 10 is set to KEY_ENTER.

See Also:: Constant Field Values

KEY_SPACE

public static final int KEY_SPACE

keyCode for the space key, U+0020 SPACE.

Constant value 32 is set to KEY_SPACE.

See Also:: Constant Field Values

KEY_BACKSPACE

public static final int KEY_BACKSPACE

keyCode for the backspace key, U+0008 BACKSPACE.

Constant value 8 is set to KEY_BACKSPACE.

See Also:: Constant Field Values

KEY_DELETE

public static final int KEY_DELETE

keyCode for the delete key, U+007F DELETE.

Constant value 127 is set to KEY_DELETE.

See Also:: Constant Field Values

KEY_ESCAPE

public static final int KEY_ESCAPE

keyCode for the escape key, U+001B ESCAPE.

Constant value 27 is set to KEY_ESCAPE.

See Also:: Constant Field Values

KEY_TAB

public static final int KEY_TAB

keyCode for the tabulation key, U+0009 HORIZONTAL TABULATION.

Constant value 9 is set to KEY_TAB.

See Also:: Constant Field Values

ACTIONS_NONE

public static final int ACTIONS_NONE

Constant for requesting the empty set of actions ACTIONS_NONE has a value of 0.

Since:: MIDP 3.0
See Also:: Constant Field Values

ACTIONS_NAVIGATION

public static final int ACTIONS_NAVIGATION

Constant for requesting the basic set of actions comprised of UP, DOWN, LEFT, RIGHT, and FIRE ACTIONS_NAVIGATION has a value of -1.

Since:: MIDP 3.0
See Also:: Constant Field Values

ACTIONS_ALL

public static final int ACTIONS_ALL

Constant for requesting the full set of actions comprised of UP, DOWN, LEFT, RIGHT, FIRE, GAME_A, GAME_B, GAME_C, and GAME_D. ACTIONS_ALL has a value of -2.

Since:: MIDP 3.0
See Also:: Constant Field Values

Constructor Detail

Canvas

protected Canvas()

Constructs a new Canvas object

Method Detail

getWidth

public int getWidth()

Gets the width in pixels of the displayable area of the Canvas. The displayable area is the area that can be directly drawn on by the Canvas Graphics object. The value returned may change during execution. If it does, the application will be notified through a call to the sizeChanged(int, int) method. If setCurrent() has not yet been called to associate this Canvas object with a particular display, this call returns the width of the primary display. In fullScreenMode, the width is the same as the value returned by Display.getWidth().

Specified by:: getWidth in class Displayable

Returns:: width of the area available for the application to draw into

getHeight

public int getHeight()

Gets the height in pixels of the displayable area of the Canvas. The displayable area is the area that can be directly drawn on by the Canvas Graphics object. The value returned may change during execution. If it does, the application will be notified through a call to the sizeChanged(int, int) method. If setCurrent() has not yet been called to associate this Canvas object with a particular display, this call returns the height of the primary display. In fullScreenMode, the height is the same as the value returned by Display.getHeight().

Specified by:: getHeight in class Displayable

Returns:: height of the area available for the application to draw into

isDoubleBuffered

public boolean isDoubleBuffered()

Checks if the Canvas is double buffered by the implementation. All implementations MUST support double buffered graphics.

Returns:: true always

hasPointerEvents

public boolean hasPointerEvents()

Deprecated. Support for pointer press and release events are determined by the Display . Use Display.hasPointerevents()

Checks if the Display to which the Canvas is set to be visible on, using Display.setCurrent(), supports pointer press and release events. Pointer press and release events MUST be supported if the underlying hardware supports this feature. If setCurrent() has not yet been called to associate this Canvas object with a particular display, this call returns information based on the primary display.

Returns:: true if the device supports pointer events If the underlying hardware supports pointer events then the return value shall always be true.

hasPointerMotionEvents

public boolean hasPointerMotionEvents()

Deprecated. Support for pointer motion events are determined by the Display . Use Display.hasPointerMotionevents()

Checks if the Display to which the Canvas is set to be visible on, using Display.setCurrent(), supports pointer motion events (pointer dragged). Applications may use this method to determine if the associated Display is capable of supporting motion events. Pointer motion events MUST be supported if the underlying hardware supports this feature. If setCurrent() has not yet been called to associate this Canvas object with a particular display, this call returns information based on the primary display.

Returns:: true if the device supports pointer motion events. If the underlying hardware supports pointer motion events then the return value shall always be true.

hasRepeatEvents

public boolean hasRepeatEvents()

Checks if the platform can generate repeat events when key is kept down. Repeat events MUST be supported by all implementations.

Returns:: true always

getKeyCode

public int getKeyCode(int action)

Gets a key code that corresponds to the specified action on the device. The implementation is required to provide a mapping for every action, so this method will always return a valid key code for every action. There may be multiple keys associated with the same action; however, this method will return only one of them. Applications should translate the key code of every key event into an action using getGameAction(int) and then interpret the resulting action, instead of generating a table of key codes at using this method during initialization.

Valid soft key actions are those placements returned from Display.getExactPlacementPositions for any of the borders as defined in Exact placement of Commands.

The mapping between key codes and actions will not change during the execution of the application. (Note: Follow link to the last paragraph in Actions section for a description of an exception case)

Parameters:: action - the action
Returns:: a key code corresponding to this action
Throws:: java.lang.IllegalArgumentException - if action is not a valid action

getKeyName

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 actions to key names. To get the string name for an action GAME_A, the application must call


 getKeyName(getKeyCode(GAME_A));

Parameters:: keyCode - the key code being requested
Returns:: a string name for the key
Throws:: java.lang.IllegalArgumentException - if keyCode is not a valid key code

getGameAction

public int getGameAction(int keyCode)

Gets the action associated with the given key code of the device. Returns zero if no action is associated with this key code. For soft key keycodes, the action returned is the placement as defined in Display for Exact Placement of Commands. For navigation and game keys the action values are listed in the Actions description.

The mapping between key codes and actions will not change during the execution of the application. (Note: Follow link to the last paragraph in the Actions section for a description of an exception case)

Parameters:: keyCode - the key code
Returns:: the Action corresponding to this key, or the soft key placement for soft keys, or 0 if none
Throws:: java.lang.IllegalArgumentException - if keyCode is not a valid key code

setFullScreenMode

public void setFullScreenMode(boolean mode)

Controls whether the Canvas is in full-screen mode or in normal mode. If Canvas is in full-screen mode, the following requirements apply:

If CommandListener is set for a Canvas, an implementation MUST display the commands in the User Interface when a key normally reserved for the delivery of commands is pressed and deliver the selected command.
If no CommandListener is set for a Canvas, an implementation MUST deliver key code events for key presses that are otherwise reserved for the delivery of commands.

Parameters:: mode - true if the Canvas is to be in full screen mode, false otherwise
Since:: MIDP 2.0

keyPressed

protected void keyPressed(int keyCode)

Called when a key is pressed.

The getGameAction() method can be called to determine what 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).

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.

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.

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 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 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(Runnable), 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 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 Display.callSerially() method provides a facility where an application can be called back after painting has completed, avoiding the danger of deadlock.

See Also:: Display.callSerially(Runnable)

showNotify

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.

hideNotify

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.

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, unless the paint mode has been set to transparent (see Canvas.setPaintMode). 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 Font.getDefaultFont();
the stroke style is 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.

Parameters:: g - the Graphics object to be used for rendering the Canvas

sizeChanged

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 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.

Overrides:: sizeChanged in class Displayable

Parameters:: w - the new width in pixels of the drawable area of the Canvas; h - the new height in pixels of the drawable area of the Canvas
Since:: MIDP 2.0

setPaintMode

public void setPaintMode(boolean opaque)

Sets the paint mode for this Canvas.

If the paint mode is opaque, the implementation may assume that the every pixel in the clip region will be rendered by the paint method. Thus, the implementation does not need to clear or reset the pixels to a suitable state prior to calling the paint method since they will all be rendered by the Canvas.

In this example, the opaque paint mode is used and the paint method renders a white background and black text, thus fully obscuring the device's background wallpaper:

 paint(Graphics g) {
     g.setColor(0xFFFFFF);
     g.fillrect(0, 0, getWidth(), getHeight());
     g.setColor(0x000000);
     g.drawString("Some Text", 10, 10, Graphics.TOP + Graphics.LEFT);
 }

If the paint mode is transparent, the implementation is responsible for appropriately filling the entire clip region prior to calling the paint method. Some devices may fill the pixels to a suitable background color, while others may fill them with a suitable background image. Hence, any pixels untouched by the paint method will be colored appropriately. In this mode, the paint method does not need to render every pixel within the clip region; it should render only those pixels within the clip region that it wishes to control the contents of. By rendering a subset of the pixels in this manner, the contents of the Canvas will appear rendered on top of the background content provided by the implementation.

In this example, the transparent paint mode is used and the paint method renders only the black text, thus making it appear on top of the device's background wallpaper:

 paint(Graphics g) {
     g.setColor(0x000000);
     g.drawString("Some Text", 10, 10, Graphics.TOP + Graphics.LEFT);
 }

The paint mode is opaque by default.

Parameters:: opaque - true to set the paint mode to opaque, false to set it to transparent
Since:: MIDP 3.0
See Also:: paint(javax.microedition.lcdui.Graphics)

setKeyListener

public void setKeyListener(KeyListener listener)

Sets a key listener for key events to this Canvas, replacing any previous KeyListener. A null reference is allowed and has the effect of removing any existing listener. The set of key delivery methods of Canvas (keyPressed(), keyRepeated() and keyReleased()) MUST work even if a KeyListener has been set, however the application should use only one of the ways to listen to key events. The method call order of Canvas methods and KeyListener methods is undefined.

Parameters:: listener - the new listener, or null to remove a listener.
Since:: MIDP 3.0

setRequiredActions

public void setRequiredActions(int actionSet)

Specifies the set of actions that must be available on touch screen devices while this Canvas is current on the foreground Display. All MIDP devices MUST support basic actions (UP, DOWN, LEFT, RIGHT, and FIRE) and MAY provide support for additional actions (GAME_A, GAME_B, GAME_C, and GAME_D). On touch screen devices, some or all of these actions may be provided using an on-screen keypad, and this method may be used to specify the specific set of actions required, thereby permitting the implementation to optimize the size of the on-screen keypad. Calls to this method should be ignored by keypad devices that do not include a touch screen. By default, the required set of actions is set to ACTIONS_NAVIGATION, and the implementation MUST ensure that at least the basic actions (UP, DOWN, LEFT, RIGHT, and FIRE) are supported. If the required set of actions is set to ACTIONS_ALL, the implementation MUST ensure that all actions (UP, DOWN, LEFT, RIGHT, and FIRE GAME_A, GAME_B, GAME_C, and GAME_D) are supported. If the required set of actions is set to ACTIONS_NONE, the implementation is not required to support any game actions and may hide the on-screen keypad if desired. The application may still receive key events for an action even if it is not included in the required set.

Parameters:: actionSet - The set of actions required by this Canvas (ACTIONS_NAVIGATION, ACTIONS_ALL, or ACTIONS_NONE)
Throws:: java.lang.IllegalArgumentException - if actionSet is not one of ACTIONS_NAVIGATION, ACTIONS_ALL, or ACTIONS_NONE
Since:: MIDP 3.0

getSoftkeyLabelCoordinates

public int[] getSoftkeyLabelCoordinates(int placement)

Gets the upper-left coordinates on the Canvas coordinate system, width, and height of the given placement. The returned values represent a rectangular area which the implementation uses for drawing a softkey at the given placement. These dimensions do not take into account any graphical effects (for example, rounded corners, key size that change due to focus change etc). If setCurrent has not yet been called to associate this Canvas object with a particular Display , this call returns the upper-left coordinates on the primary Display coordinate system, width and height for the given placement. In normal mode, this method may return values beyond the Canvas width and height or negative values. The method only returns coordinates for placements on Display.SOFTKEY_TOP, Display.SOFTKEY_BOTTOM, Display.SOFTKEY_LEFT or Display.SOFTKEY_RIGHT borders. The method throws IllegalArgumentException for placements on the Display.SOFTKEY_OFFSCREEN border.

Returns:: Gets the upper-left coordinates, width and height (x,y,width,height) of the particular placement.
Throws:: java.lang.IllegalArgumentException - if placement is not valid or if valid placement on SOFTKEY_OFFSCREEN border.
Since:: MIDP 3.0

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

MIDP3.0

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Send a comment or suggestionVersion 3.0 of Mobile Information Device Profile Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries. Copyright 2002-2009 Motorola Inc. Portions copyright 1993-2002 Sun Microsystems, Inc. and Motorola, Inc. All Rights Reserved.

javax.microedition.lcdui Class Canvas

Key Events

Actions (aka Game Actions)

Commands

Event Delivery

UP

DOWN

LEFT

RIGHT

FIRE

GAME_A

GAME_B

GAME_C

GAME_D

KEY_NUM0

KEY_NUM1

KEY_NUM2

KEY_NUM3

KEY_NUM4

KEY_NUM5

KEY_NUM6

KEY_NUM7

KEY_NUM8

KEY_NUM9

KEY_STAR

KEY_POUND

KEY_UP

KEY_DOWN

KEY_LEFT

KEY_RIGHT

KEY_SELECT

KEY_ENTER

KEY_SPACE

KEY_BACKSPACE

KEY_DELETE

KEY_ESCAPE

KEY_TAB

ACTIONS_NONE

ACTIONS_NAVIGATION

ACTIONS_ALL

Canvas

getWidth

getHeight

isDoubleBuffered

hasPointerEvents

hasPointerMotionEvents

hasRepeatEvents

getKeyCode

getKeyName

getGameAction

setFullScreenMode

keyPressed

keyRepeated

keyReleased

pointerPressed

pointerReleased

pointerDragged

repaint

repaint

serviceRepaints

showNotify

hideNotify

paint

sizeChanged

setPaintMode

setKeyListener

setRequiredActions

getSoftkeyLabelCoordinates

javax.microedition.lcdui
Class Canvas