net.rim.device.api.ui
Class VirtualKeyboard

java.lang.Object
  extended by 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:

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





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.