On-screen keypad in Canvas

Many touch enabled devices include only a limited set of physical keys. For backwards compatibility with Canvas applications, Touch UI utilizes an on-screen keypad.

Touch enabled devices with limited or no physical keys offer different kinds on-screen keypads for Canvas applications. Events from available keys in on-screen keypad map the same way as events from physical keys.

A MIDlet can define what kind of on-screen keypad is available for game actions in Canvas applications. There are three possible on-screen keypad settings. In full screen mode Canvas applications a keypad also includes two softkey buttons (left softkey and right softkey). The setting can be one of the following:

no keypad
navigation keypad keys: UP, DOWN, LEFT, RIGHT and FIRE
game actions keypad keys: UP, DOWN, LEFT, RIGHT, FIRE, GAME_A, GAME_B GAME_C and GAME_D.

The on-screen keypad is set with the Nokia-MIDlet-On-Screen-Keypad JAD attribute.

Canvas game actions map to the keypad keys as following:

Canvas game action	Keypad key
`UP`	Arrow UP
`DOWN`	Arrow DOWN
`LEFT`	Arrow LEFT
`RIGHT`	Arrow RIGHT
`FIRE`	FIRE (middle key)
`GAME_A`	GAME_A
`GAME_B`	GAME_B
`GAME_C`	GAME_C
`GAME_D`	GAME_D

Note: FIRE key in on-screen keypad behaves mostly the same way as Selection key in physical keypad. Thus if there is no on-screen keypad defined for a full screen mode Canvas application, then there are no softkeys available for mapping possible application commands. Also Canvas (normal mode and full screen mode with Commands and CommandListener defined) does not get the low-level key event from Selection key unless this is explicitly enabled. For enabling low-level key event triggering from Selection key, see Canvas implementation notes.

Note: If an application has defined the on-screen keypad setting user cannot change it. However, if the setting is not defined user can change it. The on-screen keypad setting is valid for entire MIDlet suite. By default if no keypad setting has been defined the gameactions keys keypad is displayed.

Please see the following examples of different on-screen keypads for full screen mode Canvas and normal mode Canvas.

Canvas mode and keypad setting	Portrait	Landscape
Full screen mode Navigation keys on-screen keypad setting
Full screen mode Game actions on-screen keypad setting
Normal mode Navigation keys on-screen keypad setting
Normal mode Game actions on-screen keypad setting