Canvas class is the main template for
customized 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.
Touch-enabled devices feature an On-screen keypad to supplement their physical keypads for backwards compatibility
with Canvas applications.
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.
From
Java Runtime 1.3 for S60 onwards, a full screen mode Canvas is not changed to normal mode Canvas when an Alert is called.
Situation |
Behavior of softkey or Selection key press |
|---|---|
There are |
The Options menu is presented. Note: The |
There is no |
Selection key (and other softkeys) triggers low-level key events to the MIDlet. |
There is a |
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.
From S60 3rd Edition
Feature Pack 2 onwards, in full screen Canvas, the network indicator is not shown for manufacturer domain applications, and in the operator domain
it can be suppressed with a Central Repository setting.
Note: In full screen mode Canvas in pure
touch devices (no hardware soft keys available), Commands cannot be displayed, except with the On-screen keypad or by changing Canvas mode to normal.
Canvas in Symbian is always
double buffered (isDoubleBuffered returns true), which means that each Canvas instance creates
a new back buffer for the display. Therefore using multiple Canvas instances results in high memory consumption. For
more information, see paint method description.
From
S60 3rd Edition FP 2 onwards, Canvas instances
share a common back buffer. Therefore creating many Canvas instances consumes considerably less memory.
The Canvas back buffer is currently bitmap based so the memory
consumption from the buffer is relative to the device display size.
Note: GameCanvas instances operate with
a dedicated back buffer, so the above memory performance improvement
applies only for Canvas.
Note: LCDUI Canvas graphics scaling with MMAPI VideoControl is not implemented because the MMAPI Video content is not present on the frame buffer. Therefore,
using Canvas scaling feature together with video
content via MMAPI is not recommended. Other MMAPI functionality can
be used properly (audio etc.).
For an example on double buffering, see article Using double buffering in Java ME in Forum Nokia wiki.
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.
From Java Runtime 2.1
for Symbian onwards, to ensure that Canvas content is sized correctly on the screen after the device orientation
changes, the Java Runtime might call the paint method after calling the hideNotify method.
Therefore, make sure that the paint method implemented
by your MIDlet renders the Canvas content correctly
also after a hideNotify call.
If the device
orientation changes in the following cases, the platform calls paint after first calling hideNotify:
The Options menu is open on Canvas.
Canvas is not the current Displayable but is visible behind a pop-up TextBox or Alert.
The MIDlet is no longer running on the foreground, but Canvas is still visible on the screen.
Note: This behavior differs from the MIDP specification, which
states that 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.
The following JAD attributes have an effect on Canvas behavior:
Nokia-MIDlet-Target-Display-Size - for
target device screen resolution
Nokia-MIDlet-Original-Display-Size - for
original MIDlet screen resolution
Nokia-MIDlet-Canvas-Scaling-Orientation-Switch - for supporting orientation changes between portrait and landscape
modes. For more information, see Scaling
The following system properties have an effect on Canvas behavior:
com.nokia.softkey<n>.label.location
com.nokia.softkey<n>.label.anchor
com.nokia.canvas.net.indicator.location
Note: For backwards compatibility to Symbian
releases prior to S60 3rd Edition FP 2, it is possible to enable low-level
key event triggering from Selection key both in normal mode Canvas and in full screen Canvas with Commands and CommandListener defined.
If this feature is enabled, no Commands are mapped
to Selection key. Instead the relevant low-level key event will be
triggered. Note that in a full screen mode Canvas without any Commands and CommandListener defined this feature does not have any effect as low level key events
are triggered from all softkeys in any case.
To enable this
feature the following attribute should be added to the JAD or manifest
file of the Java application with value true: Nokia-MIDlet-S60-Selection-Key-Compatibility. For more
information, see section JAD and JAR manifest
attributes.
Note: Java Runtime 2.1 for Symbian
onwards network indicators are not shown and the system property com.nokia.canvas.net.indicator.location returns null. Although Java Canvas does not
paint the network indicator, the Symbian native indicator shows network
activity when applicable.
For an example of using Canvas, see section Example: Creating a simple test MIDlet.
For an additional example, see Receiving key events in Java ME on Forum Nokia.