Launching the virtual keyboard for Canvas and CustomItem

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