org.eclipse.ercp.swt.mobile
Class MobileDevice

java.lang.Object
  org.eclipse.ercp.swt.mobile.MobileDevice

public class MobileDevice

extends java.lang.Object

Instances of this class represent the device that is being used. It provides methods that enable applications to learn more about the device specific characteristics and capabilities.

Applications can query what input features and display screens are permanently part of the device. These are considered local features. Some devices also allow input mechanisms or screens to be attached to the device at runtime. These are considered remote features. Since local features do not come and go, it is sufficient to query for them once. On the other hand, since remote devices can be added or removed at any time, an application needs to add a MobileDeviceListener to be informed of these events.

Local features may also be internal or external. External features are only available when a device is closed. Internal features are only available when a device is opened.

See Also:

Screen, Input, MobileDeviceListener

Field Summary

static int	ALERT_CRITICAL alert level indicating immediate attention is required (ex.
static int	ALERT_HIGH_IMPORTANCE alert level indicating user attention desired (ex.
static int	ALERT_LOW_IMPORTANCE alert level indicating simple notification (ex.
static int	EXTERNAL local feature which is only available when mobile device is closed
static int	INTERNAL local feature which is only available when mobile device is opened
static int	LOCAL feature which is permanently attached to the mobile device and always available
static int	REMOTE feature which is not part of the mobile device unless connected via wire or wireless signal
static int	VK_ALWAYS_OFF virtual keyboard hint indicating keyboard should always be hidden
static int	VK_ALWAYS_ON virtual keyboard hint indicating keyboard should always be visible
static int	VK_NORMAL virtual keyboard hint indicating normal show and hide operation

Method Summary

void	addMobileDeviceListener(MobileDeviceListener listener) Adds the listener to the collection of listeners who will be notified when a device configuration change occurs, by calling one of the methods defined in the MobileDeviceListener interface.
void	alert(int level) Alerts the user using device specific mechanisms such as sounds, flashing, or vibration.
Input[]	getInputs() Returns an array of Input objects describing the input features available to the device.
static MobileDevice	getMobileDevice() Returns singleton instance of MobileDevice class.
Screen[]	getScreens() Returns an array of Screen objects describing the display features available to the device.
boolean	isOpen() Returns whether device is opened.
void	removeMobileDeviceListener(MobileDeviceListener listener) Removes the listener from the collection of listeners who will be notified when a device configuration change occurs.
void	setVKStatus(int status) Sets the status of the system virtual keyboard (if one is available).

Methods inherited from class java.lang.Object

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

Field Detail

LOCAL

public static final int LOCAL

feature which is permanently attached to the mobile device and always available

See Also:

Constant Field Values

INTERNAL

public static final int INTERNAL

local feature which is only available when mobile device is opened

See Also:

Constant Field Values

EXTERNAL

public static final int EXTERNAL

local feature which is only available when mobile device is closed

See Also:

Constant Field Values

REMOTE

public static final int REMOTE

feature which is not part of the mobile device unless connected via wire or wireless signal

See Also:

Constant Field Values

ALERT_LOW_IMPORTANCE

public static final int ALERT_LOW_IMPORTANCE

alert level indicating simple notification (ex. e-mail arrival)

See Also:

Constant Field Values

ALERT_HIGH_IMPORTANCE

public static final int ALERT_HIGH_IMPORTANCE

alert level indicating user attention desired (ex. instant message arrival)

See Also:

Constant Field Values

ALERT_CRITICAL

public static final int ALERT_CRITICAL

alert level indicating immediate attention is required (ex. battery level at 1%)

See Also:

Constant Field Values

VK_NORMAL

public static final int VK_NORMAL

virtual keyboard hint indicating normal show and hide operation

See Also:

Constant Field Values

VK_ALWAYS_ON

public static final int VK_ALWAYS_ON

virtual keyboard hint indicating keyboard should always be visible

See Also:

Constant Field Values

VK_ALWAYS_OFF

public static final int VK_ALWAYS_OFF

virtual keyboard hint indicating keyboard should always be hidden

See Also:

Constant Field Values

Method Detail

addMobileDeviceListener

public void addMobileDeviceListener(MobileDeviceListener listener)

Adds the listener to the collection of listeners who will be notified when a device configuration change occurs, by calling one of the methods defined in the MobileDeviceListener interface.

screenChanged is called when a monitor configuration changes.
inputChanged is called when an input configuration changes.
deviceChanged is called when the device is opened or closed.

Parameters:

listener - instance called when device events occur

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the listener is null

SWTError -

• ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure

See Also:

removeMobileDeviceListener(org.eclipse.ercp.swt.mobile.MobileDeviceListener), MobileDeviceListener

alert

public void alert(int level)

Alerts the user using device specific mechanisms such as sounds, flashing, or vibration. Level must be one of ALERT_LOW_IMPORTANCE, ALERT_HIGH_IMPORTANCE, or ALERT_CRITICAL. The method maps these levels to device specific features that may also be dependent upon user configuration or current profile.

Parameters:

level - constant describing the importance of the alert

Throws:

java.lang.IllegalArgumentException -

• ERROR_INVALID_ARGUMENT - if level is not one of the allowed class constants

See Also:

ALERT_LOW_IMPORTANCE, ALERT_HIGH_IMPORTANCE, ALERT_CRITICAL

getInputs

public Input[] getInputs()

Returns an array of Input objects describing the input features available to the device. The return value may be null if there are no input features available.

Throws:

SWTError -

• ERROR_CANNOT_GET_SELECTION - if the operation fails because of an operating system failure

See Also:

Input

getScreens

public Screen[] getScreens()

Returns an array of Screen objects describing the display features available to the device. The return value may be null if there are no display screens available.

Throws:

SWTError -

• ERROR_CANNOT_GET_SELECTION - if the operation fails because of an operating system failure

See Also:

Screen

getMobileDevice

public static MobileDevice getMobileDevice()

Returns singleton instance of MobileDevice class.

Returns:

singleton of MobileDevice class. Must not be Null.

Throws:

SWTError -

• ERROR_CANNOT_GET_SELECTION - if the operation fails because of an operating system failure

isOpen

public boolean isOpen()

Returns whether device is opened. For devices that have no internal screens or input features, the method always returns true.

removeMobileDeviceListener

public void removeMobileDeviceListener(MobileDeviceListener listener)

Removes the listener from the collection of listeners who will be notified when a device configuration change occurs.

Parameters:

listener - instance called when device events occur

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the listener is null

SWTError -

• ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure

See Also:

addMobileDeviceListener(org.eclipse.ercp.swt.mobile.MobileDeviceListener), MobileDeviceListener

setVKStatus

public void setVKStatus(int status)

Sets the status of the system virtual keyboard (if one is available). By default, or when status is set to VK_NORMAL, a platform's normal virtual keyboard behavior is used. So generally, the virtual keyboard is displayed when a widget capable of text input gains focus and is hidden when that widget looses focus. The widgets which exhibit this behavior may be platform dependent. However, there are cases where an application may wish to continuously display the virtual keyboard or always keep it hidden. Setting the status to VK_ALWAYS_ON or VK_ALWAYS_OFF will accomplish this and the effect is immediate. Changing focus will then have no affect on the virtual keyboard. Note: By default, widgets which normally accept input but are set to read only do not cause the the virtual keyboard to display.

Parameters:

status - virtual keyboard mode. One of VK_NORMAL, VK_ALWAYS_ON, VK_ALWAYS_OFF

Throws:

java.lang.IllegalArgumentException -

• ERROR_INVALID_ARGUMENT - if the status parameter is not valid

See Also:

VK_NORMAL, VK_ALWAYS_ON, VK_ALWAYS_OFF