Physical keys and virtual keyboard

API contents

The Virtual Keyboard API consists of the following classes and interfaces (packaged as part of the Nokia UI API):

• CustomKeyboardControl

  Use the CustomKeyboardControl interface to launch and control a virtual keyboard.

• KeyboardVisibilityListener

  Use the KeyboardVisibilityListener interface to implement a listener for receiving a notification whenever the visibility of a virtual keyboard changes.

• VirtualKeyboard

  Use the VirtualKeyboard class to create a CustomKeyboardControl, retrieve information about the currently visible virtual keyboard, hide and show the default open keypad command, or register a KeyboardVisibilityListener. You can also use this class to suppress the sizeChanged event triggered whenever the visibility of a virtual keyboard changes. Suppressing the event affects both MIDlet-controlled and platform-controlled virtual keyboards.

The Virtual Keyboard API is supported since Nokia UI API 1.6.

Device compatibility

The Virtual Keyboard API is supported on Series 40 full touch devices with Java Runtime 2.0.0 for Series 40 or newer.

Using the Virtual Keyboard API

The following code snippet shows how to launch, control, and hide a virtual keyboard.

try {

    // Get the CustomKeyboardControl singleton instance
    CustomKeyboardControl vkbControl = VirtualKeyboard.getCustomKeyboardControl();

    // Launch a virtual keyboard of the specified type and in the specified mode
    vkbControl.launch(VirtualKeyboard.VKB_TYPE_ITUT, VirtualKeyboard.VKB_MODE_DEFAULT);

    // ...

    // Change the mode to numeric
    vkbControl.setKeyboardMode(VirtualKeyboard.VKB_MODE_NUMERIC);

    // ...

    // Hide the virtual keyboard
    vkbControl.dismiss();

} catch (IllegalArgumentException iae) {
    // Handle the exception
} catch (IllegalStateException ise) {
    // Handle the exception
}

You can also launch a virtual keyboard by specifying only its type or by specifying neither its type nor mode. If you do not specify the type or mode, the default platform value is used. In addition to resetting the mode after the virtual keyboard has been launched, you can also reset the type by calling the setKeyboardType method. For a list of supported types and modes, see the VirtualKeyboard class reference.

The following code snippet shows how to implement a listener for receiving a notification whenever a virtual keyboard is either launched or dismissed.

class VirtualKeyboardListener implements KeyboardVisiblityListener {

    int myDisplayHeight;

    VirtualKeyboardListener() {

        // Set the current class as KeyboardVisiblityListener
        VirtualKeyboard.setVisibilityListener(this);

        // Specify myDisplayHeight
        // ...

    }

    // Called when a virtual keyboard is launched (shown)
    void showNotify(int keyboardCategory) {

        // Determine the height left for the MIDlet UI to use
        int visibleHeight;
        try {
            visibleHeight = myDisplayHeight - VirtualKeyboard.getHeight();
        } catch (IllegalStateException ise) {
            // Handle the exception
        }

        // Refresh the screen
        // ...

    }

    // Called when a virtual keyboard is dismissed (hidden)
    void hideNotify(int keyboardCategory) {

        // The MIDlet UI can use the full height available
        int visibleHeight = myDisplayHeight;

        // Refresh the screen
        // ...

    }

}

For more information about the fields and methods provided by the Virtual Keyboard API, see the individual class and interface references.

More information

For example MIDlets that show you how to use the Virtual Keyboard API, see:

• ImageViewer

• Paint

• Scalable 2D vector graphics examples

Key events in Canvas and CustomItem

The following physical keys can be mapped to MIDP-defined logical key events. Keys marked with * are only visible on FullCanvas and in Canvas in full screen mode when there are no CommandListener or Commands set.

Some devices support 9-way navigation, which means that in addition to the four main directional keys, the device can also detect key presses to four diagonal directions. If the user presses into a diagonal direction on such a device, the Canvas or CustomItem receives two orthogonal key events from the adjacent main directions according to the following table:

The reason for separating the diagonal key presses is to maintain backwards compatibility for legacy MIDlets. Java Runtime translates single diagonal key press events to two orthogonal key press events.

A full keyboard contains also other standard physical keys, including letters and characters such as @ and +. Their key codes are equal to the Unicode value for the corresponding character. For example, the letter key A has the key code 97 and its key name string is a. A full keyboard provides also combined keys, for example Shift+A has the key code 65 and its key name string is A.

_{Modifier keys}

Every modifier key on keyboard (Shift, Fn, Ctrl) delivers a key event with key code -50 to Canvas and CustomItem key press methods. Key events from special keys such as Chr, zoom keys, and others are also delivered to MIDlet but they do not function in any special way. Thus, the MIDlet can do what they want for these key events.

Modifier keys (Shift, Fn, Ctrl) pressed along with other keys send combined key events (for example, pressing Fn+A sends @).

Modifier keys act as 'sticky' keys, modifying the immediately following character event. In other words, the end user does not have to keep the Fn key pressed down while entering the special letter. Pressing the key once is enough.

Pressing a modifier key twice locks the modifier key. Every following key press delivers modified key codes. Every locked modifier key except Shift can be unlocked by pressing it again. Pressing a locked Shift key unlocks it for one following key press. The Shift modifier is unlocked completely by pressing it twice.

Several system properties are closely related to using modifier keys. For more information, see section System properties.

Media Keys

Nokia devices are equipped with media keys from Series 40 5th Edition onwards. Media keys are play/pause, stop, previous/rewind, and next/fast forward.

Media key events are not created by default. In order for a MIDlet to be notified by media key events, the JAD attributeNokia-UI-Enhancement must have value MusicKeysSupported set, as described in table Nokia proprietary JAD attributes.

Media key events are delivered to all Canvas and CustomItem objects even when they are not the current Displayable or the focused item on a Form. Thus media applications can be managed without setting the MIDlet on the foreground. This can be especially useful when the MIDlet is managed via an accessory and the device is not at hand.

Media key presses are received with the keyPressed (int keyCode) method. If the MIDlet contains more than one active Canvas or CustomItem objects, you need to carefully manage what Canvas or CustomItem object(s) (if any) handle media key events, as all these objects will get a media key event when it occurs.

If the MIDlet contains more than one active Canvas or CustomItem objects, it is MIDlet developer’s responsibility to manage what Canvas or CustomItem object(s) (if any) handles media key events, because all these objects will get a media key event when it occurs.

For key codes of media keys, see table Additional physical keys above.