com.nokia.mid.ui
Class TactileFeedback

java.lang.Object
  com.nokia.mid.ui.TactileFeedback

public class TactileFeedback
extends java.lang.Object

This class is a Java extension to support tactile feedback (audio, vibra, piezo, etc.) on touch-enabled devices. Tactile feedback is meant to give user more clear feeling of touch events, like tapping and dragging. The actual physical tactile feedback depends on the device tactile feedback implementation, hardware and device settings. A device may implement the feedback with different hardware methods, for example, vibra, audio or piezo hardware.

The API supports both LCDUI and eSWT UI toolkits.

Using this class is safe when a device does not support tactile feedback. In this case methods of this class can be called but this has no effect.

Tactile feedback can be generated in two ways:

• By producing direct feedback from the application.
• By adding feedback areas to area registry, in which case the feedback will be produced by the tactile feedback system automatically when the defined screen area (with defined feedback) is touched.

Direct feedback is given instantly with directFeedback specifying the feedback type. Direct feedback can be used when the user action is not just a tap in a certain area. For example if the user drags from one menu item to the other the application may give direct feedback to emphasize focus traverse.

In case of area registry for eSWT Control, the registry needs to be updated every time when the size or position of a UI component changes, or when e.g. a state of a UI component changes in such way that feedback type also changes. Typically the area update may be implemented in controlMoved and controlResized methods of ControlListener interface.

In case of area registry for LCDUI Canvas or CustomItem no further actions are required to update tactile feedback areas when a CustomItem is moved in a Form or when a Canvas is changed due to e.g. orientation switch.

There are quite tight latency requirements for tactile feedback, and in most cases feedback should be triggered in less than 30ms from the time when user touched the screen. For the area registry the feedback system is responsible of fulfilling this requirement, but in case of direct feedback it is the responsibility of the user of this API.

The tactile feedback has 2 different styles: Basic and Sensitive. Each type is defined in the device settings, not by this API. Each style of feedback is used in different cases. Typically Basic style is used to emphasize the tap event, while Sensitive style is used mostly at dragging operations, to emphasize focus traverse, text selection, etc. Choosing a specific style for each use case in up to developer, however it is good to follow the behavior of native applications.

The goal of the API is to enable user-created UI components to have tactile feedback. The UI component types supported by the API are limited to user-defined components only: javax.microedition.lcdui.Canvas, javax.microedition.lcdui.CustomItem, org.eclipse.swt.widgets.Control. Other UI components (i.e. List, TextBox, etc.) get default tactile feedback automatically from the platform.

Since:

1.2

Field Summary

static int	FEEDBACK_STYLE_BASIC Constant for specifying basic tactile feedback style.
static int	FEEDBACK_STYLE_SENSITIVE Constant for specifying sensitive tactile feedback style.

Constructor Summary

TactileFeedback()
Constructs tactile feedback engine object.

Method Summary

void	directFeedback(int style) Triggers direct tactile feedback of the specified style.
boolean	isTouchFeedbackSupported() Queries the device if it supports tactile feedback.
void	moveFeedbackAreaToFirstPriority(java.lang.Object uiObject, int id) Moves the specified tactile feedback area to first priority.
void	registerFeedbackArea(java.lang.Object uiObject, int id, int x, int y, int width, int height, int style) Registers area within a UI component for tactile feedback.
void	removeFeedbackForComponent(java.lang.Object uiObject) Removes all tactile feedback for a UI component.
void	unregisterFeedbackArea(java.lang.Object uiObject, int id) Unregisters tactile feedback area within a UI component.

Methods inherited from class java.lang.Object

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

Field Detail

FEEDBACK_STYLE_BASIC

public static final int FEEDBACK_STYLE_BASIC

Constant for specifying basic tactile feedback style. Actual style behaviour is set through device settings.

See Also:

Constant Field Values

FEEDBACK_STYLE_SENSITIVE

public static final int FEEDBACK_STYLE_SENSITIVE

Constant for specifying sensitive tactile feedback style. Actual style behaviour is set through device settings.

See Also:

Constant Field Values

Constructor Detail

TactileFeedback

public TactileFeedback()

Constructs tactile feedback engine object. The object may be used in both LCDUI and eSWT Java UI toolkits. TactileFeedback object must be constructed before using any tactile feedback methods.

Method Detail

directFeedback

public void directFeedback(int style)
                    throws java.lang.IllegalArgumentException

Triggers direct tactile feedback of the specified style.

Parameters:

style - The style of the direct feedback. Use predefined values FEEDBACK_STYLE_BASIC, FEEDBACK_STYLE_SENSITIVE. Actual style behavior is set through device settings.

Throws:

java.lang.IllegalArgumentException - if the style parameter has invalid type.

isTouchFeedbackSupported

public boolean isTouchFeedbackSupported()

Queries the device if it supports tactile feedback. It is safe to use this class even if the device does not support tactile feedback. Methods of this class can be called but this has no effect.

Returns:

true if the device supports tactile feedback, false otherwise.

registerFeedbackArea

public void registerFeedbackArea(java.lang.Object uiObject,
                                 int id,
                                 int x,
                                 int y,
                                 int width,
                                 int height,
                                 int style)
                          throws java.lang.IllegalArgumentException

Registers area within a UI component for tactile feedback. If areas overlap then the feedback is given from the last registered area. moveFeedbackAreaToFirstPriority can be used to bring a certain area covered by another area into action. If an area with specified id is already registered it is updated. When updating an existing area there is no need to unregister it before re-registering again with new coordinates and/or feedback style. The area specified by x, y, width and height parameters may be located on the screen just partially.

In case of area registry for eSWT Control, the registry needs to be updated every time when the size or position of a UI component changes, or when e.g. a state of a UI component changes in such way that feedback type also changes. Typically the area update may be implemented in controlMoved and controlResized methods of ControlListener interface. The update of an area may be implemented by calling registerFeedbackArea with the same area id but new coordinates and/or feedback style.

In case of area registry for LCDUI Canvas or CustomItem no further actions are required to update tactile feedback areas when a CustomItem is moved in a Form or when a Canvas is changed due to e.g. orientation switch.

Parameters:

uiObject - The UI component for tactile feedback registration. Valid object types are: javax.microedition.lcdui.Canvas, javax.microedition.lcdui.CustomItem, org.eclipse.swt.widgets.Control.

id - Id of the new tactile feedback area to be registered. Id's are used to identify particular tactile feedback area within one UI component. Id's do not need to be consecutive numbers.

x - x-coordinate of the top-left corner of tactile feedback rectangle to register.

y - y-coordinate of the top-left corner of tactile feedback rectangle to register.

width - Width of tactile feedback rectangle to register.

height - Height of tactile feedback rectangle to register.

style - The style of the feedback for specified area. Use predefined values FEEDBACK_STYLE_BASIC, FEEDBACK_STYLE_SENSITIVE. Actual style behaviour is defined through device settings.

Throws:

java.lang.IllegalArgumentException - if the uiObject parameter has invalid type.

java.lang.IllegalArgumentException - if the style parameter has invalid type.

unregisterFeedbackArea

public void unregisterFeedbackArea(java.lang.Object uiObject,
                                   int id)
                            throws java.lang.IllegalArgumentException

Unregisters tactile feedback area within a UI component.

Parameters:

uiObject - The UI component for tactile feedback area de-registration. Valid object types are: javax.microedition.lcdui.Canvas, javax.microedition.lcdui.CustomItem, org.eclipse.swt.widgets.Control.

id - Id of the tactile feedback area to be unregistered. Id's are used to identify particular tactile feedback area within one UI component. If given id was not registered by registerFeedbackArea then the call has no effect.

Throws:

java.lang.IllegalArgumentException - if the uiObject parameter has invalid type.

removeFeedbackForComponent

public void removeFeedbackForComponent(java.lang.Object uiObject)

Removes all tactile feedback for a UI component.

Parameters:

uiObject - The UI component for tactile feedback area de-registration. Valid object types are: javax.microedition.lcdui.Canvas, javax.microedition.lcdui.CustomItem, org.eclipse.swt.widgets.Control.

Throws:

java.lang.IllegalArgumentException - if the uiObject parameter has invalid type.

moveFeedbackAreaToFirstPriority

public void moveFeedbackAreaToFirstPriority(java.lang.Object uiObject,
                                            int id)

Moves the specified tactile feedback area to first priority. Priority is significant in case of overlapping tactile feedback areas. If the tactile feedback styles of registered areas are different, the feedback from first-priority area will be given.

Parameters:

uiObject - The UI component for tactile feedback area de-registration. Valid object types are: javax.microedition.lcdui.Canvas, javax.microedition.lcdui.CustomItem, org.eclipse.swt.widgets.Control.

id - Id of the tactile feedback area to be unregistered. Id's are used to identify particular tactile feedback area within one UI component. If given id was not registered by registerFeedbackArea then the call has no effect.

Throws:

java.lang.IllegalArgumentException - if the uiObject parameter has invalid type.