Canvas

Canvas class is the main template for customised MIDlet functions. Using Canvas, the MIDlet can use any drawing primitives provided by the LCDUI Graphics interface and can receive key events. The drawback is that the MIDlet won't be as portable as ones created using only high-level APIs.

A common example of a MIDlet that uses Canvas is a mobile game that requires pixel-accurate drawing and access to low-level keypad events. At least two simultaneous key presses are supported in Canvas Displayable.

Canvas is a subclass of Displayable, and applications can attach Commands to it. This is useful for implementing high-level actions to a MIDlet. The Canvas methods hideNotify and showNotify is called to indicate when the Canvas has been obscured and unobscured, respectively.

The Canvas class has a full screen mode, where the whole display area is available to the MIDlet. The full screen mode can be activated/deactivated by the application by calling the setFullScreenMode function.

In MIDP, a virtual machine is able to trigger various events on Canvas, such as key presses, releases, repeats, and whether Canvas is still visible or not.

Canvas properties

If Canvas is in the full screen mode and it has no CommandListener, the MIDlet triggers low-level key events from the softkeys and is thus in full control of them. If there are one or more Commands, pressing any softkey shows the Options menu even though there is no control pane visible and thus there are no softkey labels visible.

The title and the Ticker are not displayed for a Canvas in full-screen mode.

A full screen mode Canvas is changed to a normal mode Canvas when an Alert is called and displayed on top of the Canvas. After the Alert is dismissed, the Canvas is changed back to full screen mode.

After the Alert is dismissed, on Nokia Asha software platform devices, the Canvas instance remains in normal mode.

**Table:** Softkey behavior in different situations with full screen mode Canvas
Situation	Behavior of softkey or Selection key press
There are `Commands` and a `CommandListener` defined	The Options menu is presented. Note: The `Commands` are not directly associated with the softkeys but shown in the Options menu.
There is no `CommandListener` set for Canvas in full screen mode.	Selection key (and other softkeys) triggers low-level key events to the MIDlet.
There is a `CommandListener` but no Commands set for Canvas in full screen mode.	Selection key (and other softkeys) triggers low-level key events to the MIDlet.

Note:

Canvas in normal mode does not get the low-level key events even if there is no CommandListener.

Since there is no universal indicator pane to show the network activity indicator, the full screen mode Canvas renders a connection indicator on top of the main pane. Indicator differs depending on the network bearer.

Command behavior on full screen canvas mode

On non-touch devices, when the Canvas is in full screen mode and it has a CommandListener and one or more Commands, then pressing of any softkey opens the options menu. The options menu contains all Commands that are added to the Canvas.

When the Canvas is in full screen mode but CommandListener has not been set to it or CommandListener has been set but there are no Commands added to the Canvas, then pressing of a softkey posts a key event to Java Canvas.

On Series 40 touch and type and full touch devices Commands appended to a full screen canvas are not displayed, if the pointerPressed, pointerReleased and pointerDragged methods contain a custom implementation. If no custom implementation has been given for these methods, the Commands are activated by tapping the center of bottom of the screen, where there is a dedicated square as seen in the image below.

Figure: Full screen canvas mode with appended Commands that can be launched from the bottom of the screen

Tapping this area results in a pop up menu on Series 40 full touch devices, that corresponds to the context specific Option’s Menu, or the emergence of the virtual soft keys on touch and type devices.

On Nokia Asha software platform devices, you can swipe the Commands in the Option's menu from the bottom of the screen, whether there is a custom implementation of the pointerPressed, pointerDragged and pointerReleased methods, or not.

Touch interaction in Canvas and CustomItem

Unlike High-level UI components, the low-level elements Canvas and CustomItem do not automatically implement touch functionality. Instead, you need to implement the functionality separately by receiving touch events for these elements and then handling the events appropriately. You can also use gestures events and multipoint touch API to implement the touch functionality.

To receive and handle touch events for Canvas or CustomItem:

Use the following methods to check whether the platform supports touch events:
- For Canvas, use hasPointerEvents and hasPointerMotionEvents.
- For CustomItem, use getInteractionModes.
Touch events are registered as pointer events. To receive these events, implement the following Canvas or CustomItem methods:
- The pointerPressed method is called on touch down events ("pointer is pressed").
- The pointerDragged method is called on drag events ("pointer is dragged").
- The pointerReleased method is called on touch release events ("pointer is released").
The corresponding coordinates are passed to the MIDlet. Top left is indicated as 0,0.
Handle the touch events (pointer events) in the above methods, or use the above methods to call separately defined event handlers.
For more information about the different event combinations that make up touch actions, see table Basic touch actions.

Showing and hiding the status zone

By default, the status zone (at the top of the screen) is hidden when a Canvas is in full screen mode. MIDlets can show and hide the status zone using the LCDUIUtil.setObjectTrait method with nokia.ui.canvas.status_zone as the trait to set:

To show the status zone, call:

LCDUIUtil.setObjectTrait(myCanvasInstance, "nokia.ui.canvas.status_zone", Boolean.TRUE);

To hide the status zone, call:

LCDUIUtil.setObjectTrait(myCanvasInstance, "nokia.ui.canvas.status_zone", Boolean.FALSE);

The nokia.ui.canvas.status_zone trait is supported since Java Runtime 2.0.0 for Series 40 and Java runtime for Nokia Asha software platform devices.

More information

For an example of using Canvas, see section Example: Creating a simple test MIDlet.

For an additional example, see article Receiving key events in Java ME in the Nokia Developer Wiki.

Font

Texts used in the softkeys are displayed as in the native UI, using the phone’s selected language (fonts may vary with the language selected on the phone). However the drawChar(), drawChars() and drawstring() methods of the Graphics class render text based on the current active Font in the Graphics context set by the MIDlet.

Default font in Canvas (returned by Font.getDefaultFont() method) is STYLE plain and SIZE medium.

the only font style requests supported in ChoiceGroups and Lists are plain, bold and italic. Underlined and combination styles are not supported.

The user may download applications which use a different language to the current language setting in their phone. For example, a string containing Chinese characters would use the APAC layout since these are the largest characters. If the resulting string contains a mix of Nokia fonts, it is the layout of the largest font which dictates the layout used on the display. For example, a string containing both Latin and Chinese characters, would use the APAC layout since these are the largest characters.

More information

For more information about Canvas see: