net.rim.device.api.ui
Class VirtualKeyboard

java.lang.Object
  net.rim.device.api.ui.VirtualKeyboard

public abstract class VirtualKeyboard
extends Object

For supported devices with touchscreens, the virtual keyboard allows the user to type using the display in either SureType or QWERTY keyboard mode (depending on device orientation). A VirtualKeyboard object is a context-specific handle to the system-managed virtual keyboard. The context for a VirtualKeyboard is a Screen, and applications should obtain instances by invoking Screen.getVirtualKeyboard().

Keyboard visibility

In general, applications are not required to actively manage the visibility of the virtual keyboard. Each Screen is associated with a VirtualKeyboard object that contains a default visibility state. However, when a Screen is initialized, the application can call VirtualKeyboard.setVisibility(int) to specify the visibility style for the context. If the visibility style calls for restoring the previous virtual keyboard visibility whenever the context is active, the system handles saving and restoring the visibility state.

The visibility styles are:

• VirtualKeyboard.HIDE
• VirtualKeyboard.SHOW
• VirtualKeyboard.HIDE_FORCE
• VirtualKeyboard.SHOW_FORCE
• VirtualKeyboard.IGNORE
• VirtualKeyboard.RESTORE

Keyboard layout

The keyboard layout that is displayed is determined by the edit field styles and text filters that are set for the field with input focus. See Field and BasicEditField for more information about field styles, and Keypad.getHardwareLayout() for more information on keyboard layouts.

Since:

BlackBerry API 4.7.0

Field Summary
static int	HIDE When passed to VirtualKeyboard.setVisibility(int), indicates the keyboard should be hidden either the next time the context has focus, or immediately if the context is already has focus.
static int	HIDE_FORCE When passed to VirtualKeyboard.setVisibility(int), indicates the keyboard should always be hidden when the context has focus, and that displaying the keyboard should not be permitted.
static int	IGNORE When passed to VirtualKeyboard.setVisibility(int), indicates the keyboard visibility should always be ignored when the context is active.
static int	RESTORE When passed to VirtualKeyboard.setVisibility(int), indicates the keyboard visibility should always be restored to its previous state when the context is active.
static int	SHOW When passed to VirtualKeyboard.setVisibility(int), indicates the keyboard should be displayed the next time the context has focus, or immediately if the context already has focus.
static int	SHOW_FORCE When passed to VirtualKeyboard.setVisibility(int), indicates the keyboard should always be displayed when the context has focus, and that hiding the keyboard should not be permitted.

Method Summary
abstract int	getVisibility() Returns the keyboard visibility when the context has focus.
static boolean	isSupported() Indicates that the system supports the virtual keyboard.
abstract void	setVisibility(int visibility) Sets the keyboard visibility style that should be used when the context has focus.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

HIDE

public static final int HIDE

When passed to VirtualKeyboard.setVisibility(int), indicates the keyboard should be hidden either the next time the context has focus, or immediately if the context is already has focus. Subsequently, the visibility state should be automatically saved and restored.

When returned by VirtualKeyboard.getVisibility(), indicates the keyboard is hidden.

See Also:

Constant Field Values

Since:

BlackBerry API 4.7.0

SHOW

public static final int SHOW

When passed to VirtualKeyboard.setVisibility(int), indicates the keyboard should be displayed the next time the context has focus, or immediately if the context already has focus. Subsequently, the visibility state should be automatically saved and restored.

When returned by VirtualKeyboard.getVisibility(), indicates the keyboard is displayed.

See Also:

Constant Field Values

Since:

BlackBerry API 4.7.0

HIDE_FORCE

public static final int HIDE_FORCE

When passed to VirtualKeyboard.setVisibility(int), indicates the keyboard should always be hidden when the context has focus, and that displaying the keyboard should not be permitted.

See Also:

Constant Field Values

Since:

BlackBerry API 4.7.0

SHOW_FORCE

public static final int SHOW_FORCE

When passed to VirtualKeyboard.setVisibility(int), indicates the keyboard should always be displayed when the context has focus, and that hiding the keyboard should not be permitted.

See Also:

Constant Field Values

Since:

BlackBerry API 4.7.0

IGNORE

public static final int IGNORE

When passed to VirtualKeyboard.setVisibility(int), indicates the keyboard visibility should always be ignored when the context is active. The system will continue to save the keyboard visibility state, but will not restore it when the context is active.

See Also:

Constant Field Values

Since:

BlackBerry API 4.7.0

RESTORE

public static final int RESTORE

When passed to VirtualKeyboard.setVisibility(int), indicates the keyboard visibility should always be restored to its previous state when the context is active.

See Also:

Constant Field Values

Since:

BlackBerry API 4.7.0

Method Detail

isSupported

public static final boolean isSupported()

Indicates that the system supports the virtual keyboard.

Returns:

true if the system supports the virtual keyboard, false otherwise.

Since:

BlackBerry API 4.7.0

setVisibility

public abstract void setVisibility(int visibility)

Sets the keyboard visibility style that should be used when the context has focus.

Parameters:

visibility - One of VirtualKeyboard.HIDE, VirtualKeyboard.SHOW, VirtualKeyboard.HIDE_FORCE, VirtualKeyboard.SHOW_FORCE, VirtualKeyboard.IGNORE, or VirtualKeyboard.RESTORE.

Throws:

IllegalArgumentException - when visibility is not one of the VirtualKeyboard constants.

Since:

BlackBerry API 4.7.0

getVisibility

public abstract int getVisibility()

Returns the keyboard visibility when the context has focus.

Since:

BlackBerry API 4.7.0