Tactile -feedback client API

The Tactile feedback client API is a library API that has been implemented -with a client-server technique. A major part of the processing is done on -the client side, and thus API calls don't necessarily generate a client-server -transaction immediately. Instead for example, changes to area registry are -buffered, and then transferred to server-side at once.

You can use tactile feedback in, for example, the following cases:

When the user starts to scroll with the scroll bar, user can feel and/or -hear when the scroll bar thumb has been caught.
When button is pressed, user can feel and/or hear the button being pressed.

The concept of logical feedback type is very important from this API's -point of view.

In practice it means that, for example, you should not try to use this -API for producing vibrator feedback only. Instead, logical feedback types -such as "basic" or "sensitive" are used on this level, and the actual physical -effect then depends on the settings and device configuration. This way the -feedback works in a unified way from the end user point of view in the whole -device.

For user experience -guidelines on tactile feedback, see Tactile -feedback.

For information on using the API, see Providing -tactile feedback for touch events.

For the Tactile feedback client -API classes and header files, see Classes and Definitions.

API class structure

All -functionality of the Tactile feedback client API is provided in the class MTouchFeedback.

Constraints

This -API is valid for all platforms running on Symbian OS v9.4 or later.

Error handling

The -leave mechanism of Symbian environment is used to handle memory exhaustion. -The panic mechanism is not used.

The table below presents possible -error conditions and responses to them.

-Possible error situations when using Tactile Feedback Client API - - - -Error situation -Response - - - - -SetFeedbackArea returns KErrNoMemory in -case of an OOM situation. -This error can usually be ignored by the application. - - -SetFeedbackArea returns KErrArgument -The given CCoeControl pointer is a NULL pointer -or the control does not have any window associated with it (the feedback area -setting is attempted before SetContainerWindow has been called -on the control). - - -SetFeedbackArea returns KErrNotSupported. -The given logical feedback type or triggering event type is out of -range. - - -A tactile feedback enabled control is moved with CCoeControl::SetPosition, -but the feedback area is not moved. -The control must override the CCoeControl::PositionChanged function, -and update the feedback area there the same way as in the SizeChanged function. - - -Area registry updates not are effective fast enough. This might happen -in some applications which use very many frequently running active objects, -so that the CIdle object used by the implementation of this -API gets no change to run. -Use the FlushRegistryUpdates function for forcing -an update to the server side after doing all updates on the client side. - - -A control's feedback areas are not automatically disabled when the -control is dimmed. -CCoeControl::SetMopParent has not been called on the -control, and thus the object provider hierarchy is broken. - - - -

Memory overhead

Using -direct feedback does not cause additional memory overhead.

Area registry -based feedback consumes approximately 32 bytes for each feedback area.

Extensions -to the API

New logical feedback types can be added in later releases. -Otherwise the Tactile feedback client API does not explicitly support any -kinds of extensions to it.

+ + + + + +Tactile +feedback client APIThe Tactile feedback client API is used for producing tactile feedback +for different touch events. +

The Tactile feedback client API is a library API that has been implemented +with a client-server technique. A major part of the processing is done on +the client side, and thus API calls don't necessarily generate a client-server +transaction immediately. Instead for example, changes to area registry are +buffered, and then transferred to server-side at once.

You can use tactile feedback in, for example, the following cases:

When the user starts to scroll with the scroll bar, user can feel and/or +hear when the scroll bar thumb has been caught.
When button is pressed, user can feel and/or hear the button being pressed.

The concept of logical feedback type is very important from this API's +point of view.

In practice it means that, for example, you should not try to use this +API for producing vibrator feedback only. Instead, logical feedback types +such as "basic" or "sensitive" are used on this level, and the actual physical +effect then depends on the settings and device configuration. This way the +feedback works in a unified way from the end user point of view in the whole +device.

For user experience +guidelines on tactile feedback, see Tactile +feedback.

For information on using the API, see Providing +tactile feedback for touch events.

For the Tactile feedback client +API classes and header files, see Classes and Definitions.

API class structure

All +functionality of the Tactile feedback client API is provided in the class MTouchFeedback.

Changes and release information

The Tactile feedback +client API is an SDK API and first released in S60 5th Edition.

Constraints

This +API is valid for all platforms running on Symbian OS v9.4 or later.

Error handling

The +leave mechanism of Symbian environment is used to handle memory exhaustion. +The panic mechanism is not used.

The table below presents possible +error conditions and responses to them.

+Possible error situations when using Tactile Feedback Client API + + + +Error situation +Response + + + + +SetFeedbackArea returns KErrNoMemory in +case of an OOM situation. +This error can usually be ignored by the application. + + +SetFeedbackArea returns KErrArgument +The given CCoeControl pointer is a NULL pointer +or the control does not have any window associated with it (the feedback area +setting is attempted before SetContainerWindow has been called +on the control). + + +SetFeedbackArea returns KErrNotSupported. +The given logical feedback type or triggering event type is out of +range. + + +A tactile feedback enabled control is moved with CCoeControl::SetPosition, +but the feedback area is not moved. +The control must override the CCoeControl::PositionChanged function, +and update the feedback area there the same way as in the SizeChanged function. + + +Area registry updates not are effective fast enough. This might happen +in some applications which use very many frequently running active objects, +so that the CIdle object used by the implementation of this +API gets no change to run. +Use the FlushRegistryUpdates function for forcing +an update to the server side after doing all updates on the client side. + + +A control's feedback areas are not automatically disabled when the +control is dimmed. +CCoeControl::SetMopParent has not been called on the +control, and thus the object provider hierarchy is broken. + + + +

Memory overhead

Using +direct feedback does not cause additional memory overhead.

Area registry +based feedback consumes approximately 32 bytes for each feedback area.

Extensions +to the API

New logical feedback types can be added in later releases. +Otherwise the Tactile feedback client API does not explicitly support any +kinds of extensions to it.

\ No newline at end of file