com.nokia.mid.ui
Interface CustomKeyboardControl

public interface CustomKeyboardControl

Some touch devices may want to use a virtual keyboard as a replacement for the physical keyboard and thus allow user to have keypad for input. CustomKeyboard provides method for MIDlets to open virtual keyboard for key presses that are handled in Displayables keyPressed(int) method. CustomKeyboardControl does not provide editor services and platform editor controlled keyboards are not controllable by CustomKeyboardControl

CustomKeyboardControl is a singleton interface that provides access and control over the custom virtual keyboard. Java platform keyboards and editors are not controllable by this interface.

Because the virtual keyboard control covers parts of the display which would otherwise be available to the application, MIDlets may choose to only display keypad at certain times, e.g. when the MIDlet requires input from the user, this is made possible with launch().

Virtual keyboard can be launched when current Displayable is Canvas, javax.microedition.lcdui.GameCanvas or current focused item is CustomItem and current display orientation is supported by the keypad. Keypad input is directed to keyPressed method just as physical keypad input is.

The platform supports a number of different virtual keyboards, these are: VirtualKeyboard.VKB_TYPE_ITUT and VirtualKeyboard.VKB_TYPE_GAME

The appearance of the keyboard can be set using setKeyboardMode(int). Options are: VirtualKeyboard.VKB_MODE_DEFAULT, VirtualKeyboard.VKB_MODE_NUMERIC, VirtualKeyboard.VKB_MODE_ALPHA_LOWER_CASE, VirtualKeyboard.VKB_MODE_ALPHA_UPPER_CASE and VirtualKeyboard.VKB_MODE_ALPHA_UPPER_CASE_LOCKED

To display a keyboard it needs to be launched using CustomKeyboardControl

      CustomKeyboardControl vkbControl;
      vkbControl = VirtualKeyboard.getCustomKeyboardControl();
      vkbControl.launch(VirtualKeyboard.VKB_TYPE_ITUT, VirtualKeyboard.VKB_MODE_DEFAULT);
 

Keyboard can be dismissed by calling dismiss()

Virtual keyboard is set as hidden when one of the following conditions happens: user dismisses keypad, MIDlet calls dismiss(), current Displayable is changed, MIDlet is set to background or java platorm editor controlled keypad is launched. Alert is an exception which does not cause visible custom keyboard to be dismissed.

Field Summary

static int	KEYBOARD_LANDSCAPE Orientation constant for landscape
static int	KEYBOARD_LANDSCAPE_180 Orientation constant for landscape 180 degree rotation
static int	KEYBOARD_PORTRAIT Orientation constant for portrait
static int	KEYBOARD_PORTRAIT_180 Orientation constant for portrait 180 degree rotation

Method Summary

void	dismiss() Hides currently visible custom keyboard.
int	getKeyboardMode() Returns currently visible custom keyboard mode.
int	getKeyboardType() Returns currently visible custom keyboard type.
int	getSupportedOrientations(int vkbType) Method for querying supported orientations for particular keyboard type.
void	launch() Launch custom virtual keyboard.
void	launch(int type) Launch custom virtual keyboard with custom type.
void	launch(int type, int mode) Launch custom virtual keyboard with custom type and mode.
void	setKeyboardMode(int mode) Changes currently visible custom keyboard mode.
void	setKeyboardType(int type) Changes currently visible custom keyboard type.

Field Detail

KEYBOARD_LANDSCAPE

public static final int KEYBOARD_LANDSCAPE

Orientation constant for landscape

See Also:

Constant Field Values

KEYBOARD_PORTRAIT

public static final int KEYBOARD_PORTRAIT

Orientation constant for portrait

See Also:

Constant Field Values

KEYBOARD_LANDSCAPE_180

public static final int KEYBOARD_LANDSCAPE_180

Orientation constant for landscape 180 degree rotation

See Also:

Constant Field Values

KEYBOARD_PORTRAIT_180

public static final int KEYBOARD_PORTRAIT_180

Orientation constant for portrait 180 degree rotation

See Also:

Constant Field Values

Method Detail

launch

public void launch(int type,
                   int mode)

Launch custom virtual keyboard with custom type and mode. Custom virtual keyboard can be launched only when current displayable is Canvas or javax.microedition.lcdui.GameCanvas and display orientation is supported. MIDlet can query supported display orientations using getSupportedOrientations(int). If system keyboard is visible launch is not allowed.

When keyboard is shown, java platform will call Displayable.sizeChanged(int, int) that reflects new visible area available for MIDlets.

Parameters:

type - type of the keyboard. Type can be one of the following: VirtualKeyboard.VKB_TYPE_ITUT or VirtualKeyboard.VKB_TYPE_GAME

mode - mode of the keyboard. Mode can be one of the following: VirtualKeyboard.VKB_MODE_DEFAULT, VirtualKeyboard.VKB_MODE_NUMERIC, VirtualKeyboard.VKB_MODE_ALPHA_LOWER_CASE, VirtualKeyboard.VKB_MODE_ALPHA_UPPER_CASE or VirtualKeyboard.VKB_MODE_ALPHA_UPPER_CASE_LOCKED

Throws:

java.lang.IllegalArgumentException - if type or mode is not valid

java.lang.IllegalStateException - if current Displayable is not Canvas, javax.microedition.lcdui.GameCanvas, current focused item is not CustomItem or current display orientation is not supported. Exception is also thrown if VirtualKeyboard.SYSTEM_KEYBOARD is visible.

launch

public void launch(int type)

Launch custom virtual keyboard with custom type. Mode is VirtualKeyboard.VKB_MODE_DEFAULT

When keyboard is shown, java platform will call Displayable.sizeChanged(int, int) that reflects new visible area.

Parameters:

type - type of the keyboard. Type can be one of the following: VirtualKeyboard.VKB_TYPE_ITUT or VirtualKeyboard.VKB_TYPE_GAME

Throws:

java.lang.IllegalArgumentException - if type is not valid

java.lang.IllegalStateException - if current Displayable is not Canvas, javax.microedition.lcdui.GameCanvas, current focused item is not CustomItem or current display orientation is not supported. Exception is also thrown if VirtualKeyboard.SYSTEM_KEYBOARD is visible.

launch

public void launch()

Launch custom virtual keyboard. Type is VirtualKeyboard.VKB_TYPE_ITUT and mode VirtualKeyboard.VKB_MODE_DEFAULT

When keyboard is shown, java platform will call Displayable.sizeChanged(int, int) that reflects new visible area. Exception is also thrown if VirtualKeyboard.SYSTEM_KEYBOARD is visible.

Throws:

java.lang.IllegalStateException - if current Displayable is not Canvas, javax.microedition.lcdui.GameCanvas, current focused item is not CustomItem or current display orientation is not supported

dismiss

public void dismiss()

Hides currently visible custom keyboard. If custom keyboard is already hidden this method call will not do anything

setKeyboardType

public void setKeyboardType(int type)

Changes currently visible custom keyboard type. If custom keyboard is hidden this method call will not do anything

Parameters:

type - which must be on of the following: VirtualKeyboard.VKB_TYPE_ITUT or VirtualKeyboard.VKB_TYPE_GAME

Throws:

java.lang.IllegalArgumentException - if type is not valid

setKeyboardMode

public void setKeyboardMode(int mode)

Changes currently visible custom keyboard mode. Mode change will have an effect to the appearance of the keypad. If custom keyboard is hidden this method call will not do anything

Parameters:

mode - which must be one of the following: VirtualKeyboard.VKB_MODE_DEFAULT, VirtualKeyboard.VKB_MODE_NUMERIC, VirtualKeyboard.VKB_MODE_ALPHA_LOWER_CASE, VirtualKeyboard.VKB_MODE_ALPHA_UPPER_CASE or VirtualKeyboard.VKB_MODE_ALPHA_UPPER_CASE_LOCKED

Throws:

java.lang.IllegalArgumentException - if mode is not valid

getKeyboardMode

public int getKeyboardMode()

Returns currently visible custom keyboard mode. If keyboard is not visible this will return last visible keyboard mode

Returns:

keyboard input mode VirtualKeyboard.VKB_MODE_DEFAULT, VirtualKeyboard.VKB_MODE_NUMERIC, VirtualKeyboard.VKB_MODE_ALPHA_LOWER_CASE, VirtualKeyboard.VKB_MODE_ALPHA_UPPER_CASE or VirtualKeyboard.VKB_MODE_ALPHA_UPPER_CASE_LOCKED

getKeyboardType

public int getKeyboardType()

Returns currently visible custom keyboard type. If keyboard is not visible this will return last visible keyboard type

Returns:

keyboard type VirtualKeyboard.VKB_TYPE_ITUT or VirtualKeyboard.VKB_TYPE_GAME

getSupportedOrientations

public int getSupportedOrientations(int vkbType)

Method for querying supported orientations for particular keyboard type.

Parameters:

vkbType - keyboard type for which supported orientation is queried. Type must be VirtualKeyboard.VKB_TYPE_ITUT or VirtualKeyboard.VKB_TYPE_GAME

Returns:

Supported orientations. This method can return multiple supported orientations. Possible values are KEYBOARD_LANDSCAPE, KEYBOARD_PORTRAIT, KEYBOARD_LANDSCAPE_180 and KEYBOARD_PORTRAIT_180

Throws:

java.lang.IllegalArgumentException - if keyboard type is not supported