MTouchFeedback Class Reference

Changes feedback area in the registry.

The area must have been originally added to the registry with SetFeedbackArea -function, or otherwise this function will do nothing.

This function is intended to be used especially in portrait / landscape changes.

If given CCoeControl pointer is NULL, then this function call does nothing.

Since:

S60 5.0

Parameters:

	aControl	- The control, who has registered the area.
	aIndex	- The index number of the area, that will be changed.
	aNewRect	- New area rectangle for given feedback area.

Changes feedback type in the registry.

Feedback can be temporarily disabled by giving ETouchFeedbackNone as parameter (although using EnableFeedbackForControl function with parameter EFalse is usually better for this functionality).

The area must have been originally added to the registry with SetFeedbackArea -function, or otherwise this function will do nothing.

If given control pointer is NULL, then this function call is ignored.

Since:

S60 5.0

Parameters:

	aControl	- The control, who has registered the area.
	aIndex	- The index number of the area, that will be changed.
	aNewType	- New feedback type for the area.

Can be used for querying, whether given control has a feedback area defined with given index number.

It does not matter whether the areas are disabled or enabled for the moment.

Notice that one should not usually call this function, as it is always allowed to call for example RemoveFeedbackArea -function without checking if the area really exists (this is done internally in the API implementation anyway).

Since:

S60 5.0

Parameters:

	aControl	- Pointer to the control, whose feedback is queried.
	aIndex	- The index number of the area which is queried.

Returns:

ETrue if the given control has a feedback area defined with given index number. EFalse otherwise.

Can be used for querying, whether given control has any feedback areas registered.

It does not matter whether the areas are disabled or enabled for the moment.

Notice that one should not usually call this function, as it is always allowed to call for example RemoveFeedbackArea -function without checking if the area really exists (this is done internally in the API implementation anyway).

Since:

S60 5.0

Parameters:

aControl

- Pointer to the control, whose feedback is queried.

Returns:

ETrue if the given control has at least one feedback area defined. EFalse otherwise.

Creates a new touch feedback instance.

The usage of this function should only be necessary from processes which are not GUI applications, but which still have user interface (or want to play direct feedback).

DestroyInstance -function must be called for deleting the instance when it is no longer needed.

Since:

S60 5.0

Returns:

Pointer to new touch feedback instance.

Destroys the touch feedback instance and clears pointer in thread local storage.

This function must only be used in case touch feedback has been created with CreateInstanceL -function. I.e. normal GUI applications should never call this function.

Since:

S60 5.0

This function can be used for separately enabling or disabling audio- and vibra feedback for the given control.

Otherwise the function behaves in the same way as the overload with only one TBool parameter.

Any control that uses this function must call RemoveFeedbackForControl -function in its destructor.

Since:

S60 5.0

Parameters:

	aControl	- Pointer to control, whose audio- and vibra feedback will be enabled or disabled according to given parameters.
	aEnableVibra	- Use EFalse for temporary disabling the vibra feedback for this control, and ETrue for restoring the situation to normal.
	aEnableAudio	- Use EFalse for temporary disabling the audio feedback for this control, and ETrue for restoring the situation to normal.

This function enables or disables all feedback areas registered for the given control.

Disabling also affects to the overloaded version of InstantFeedback -function, so that feedback is not played if the control given as parameter has its feedback disabled.

This function can be used for temporarily disabling the feedback for some given control. Calling with second parameter ETrue re-enables feedback areas, but it still does not guarantee any feedback (control can be dimmed, invisible, of may not even have any feedback areas registered).

This function affects both vibra- and audio feedback.

Any control that uses this function must call RemoveFeedbackForControl -function in its destructor.

Since:

S60 5.0

Parameters:

	aControl	- Pointer to control, whose feedback will be enabled or disabled according to second parameter.
	aEnable	- Use EFalse for temporary disabling the feedback for this control, and ETrue for restoring the situation to normal.

Used to check whether feedback is enabled for this application.

Notice that this function only returns what was given as parameter to SetFeedbackEnabledForThisApp -function. I.e. this function can return ETrue even if feedback would be currently disabled from settings.

If only vibra or audio feedback is enabled, this function still returns ETrue.

Since:

S60 5.0

Returns:

ETrue if feedback is enabled for this application.

This function forces all registry changes made on client side to be sent to server side immediately.

This operation causes always immediate and synchronous client-server transaction, and can possibly also cause flushing of window server client side buffer. Hence this function should only be used in case there is a synchronization problem so that feedback triggered from area registry does not correspond to the areas defined by application.

This function is only likely to help in such situation, where this application's active objects are running all the time for several seconds, because in that case updates won't be transferred to server immediately.

Calling this function has no effect in case there are no pending area registry updates.

Since:

S60 5.0

Used for acquiring a pointer to touch feedback instance.

Pointer is retrieved from thread local storage, and thus it is best to store the returned pointer as member variable in case it will be needed frequently.

NULL is returned in case there is no instance. In that case CreateInstanceL -function can be used for creating a new instance.

Since:

S60 5.0

Returns:

Pointer to touch feedback instance created for this application process.

Gives direct feedback if given control has not disabled it.

This function only gives feedback, if EnableFeedbackForControl function has NOT been called on given control with second parameter EFalse.

This overload is recommended when feedback is triggered from UI controls, because then the owner of the control can decide whether both area registry based and direct feedback should be enabled or not.

If feedback is enabled for the given control, then this function causes a synchronous client-server transaction, and potentially flushing of window server client-side buffer.

Since:

S60 5.0

Parameters:

	aControl	- The control, who fishes to play feedback.
	aType	- The logical feedback type to play.

Gives direct feedback.

Notice that the feedback might not be actually played, if for example user has disabled the feedback from the settings.

This function always causes a synchronous client-server transaction, and potentially flushing of window server client-side buffer.

Since:

S60 5.0

Parameters:

aType

- The logical feedback type to play.

Makes the given feedback area the first priority area in the window where it is located.

In practice this means that this will be the first area that is hit tested when a pointer event arrives.

Notice however, that this area will only keep its top priority status until the next area is added to the registry, or until this function is called again for some other area. I.e. there is no way for giving any area a permanent status as top priority area (Registry works as a stack, and new items are added on top).

If given control pointer is NULL, this function call does nothing.

Since:

S60 5.0

Parameters:

	aControl	- The control, who has registered the area.
	aIndex	- The index number of the area, which will be prioritized.

Removes feedback area from the registry.

This function is designed to be used in case feedback areas need to be removed elsewhere than in control's destructor. In control's destructor RemoveFeedbackForControl -function must be used instead.

Since:

S60 5.0

Parameters:

	aControl	- The control, who has registered the area.
	aIndex	- The index of the area to be removed.

Removes all feedback areas of specified control from registry.

This function also clears all related data that has been cached by the API implementation, and thus it must always be called from control's destructor in case control has used any of the following functions:

• SetFeedbackArea
• EnableFeedbackForControl

Especially notice that it is not enough to remove all feedback areas individually by using RemoveFeedbackArea -function.

The difference between this function and EnableFeedbackForControl -function is that this function really removes all areas related to this control from registry, whereas EnableFeedbackForControl (when EFalse if given as parameter) only temporarily disables those areas.

Since:

S60 5.0

Parameters:

aControl

- Pointer to the control, whose area registry entries and cached information will be removed.

Sets or updates rectangular feedback area to registry.

If this is new area (i.e. there is not yet area with given control address and area index in the registry), then this area will be added as the top priority area for its window, i.e. this area will be hit test first when pointer event arrives.

Notice however, that this area will remain as top priority area only until the next new area is added to the registry, or until MoveFeedbackAreaToFirstPriority -function is called. I.e. new areas are always put on top priority, but they will only remain on top until they will be overridden by next area.

The control that is given as parameter should usually be the one that is responsible of handling the pointer events on the corresponding feedback area.

The area can later be identified by passing control pointer and index as parameters to the other functions (for modifying or removing the feedback area). In case control only registers one area, then index 0 can always be used. Usually most sensible approach is to use indexes 1, 2, 3 etc. for additional feedback areas, but in practice any desired index values can be used.

Notice that if given control is dimmed, then feedback type will be set to "None". If given control is not visible, then feedback area will not be added to registry at all (for now). However, registry is automatically updated when control's dimming or visibility changes, so one can call this function also for dimmed and invisible control.

When the control given as parameter to this function is destroyed, then the RemoveFeedbackForControl -function must be called while giving the same control as parameter again. This is necessary for removing all the feedback areas, and also for resetting the state information stored by the API implementation.

Since:

S60 5.0

Parameters:

	aControl	- The control handling pointer events on this feedback area.
	aIndex	- The index number of the area to be added.
	aRect	- The feedback area rectangle.
	aFeedbackType	- The logical feedback type given
	aEventType	- The pointer event type that triggers the feedback (currently only ETouchEventStylusDown is supported).

Returns:

KErrNone, or one of standard Symbian OS error codes if setting of area to registry failed. Some specific error codes: KErrArgument - A NULL pointer was given as first parameter, or the given control does not have any window associated to it. KErrNotSupported - Unsupported logical feedback type or event type was given as parameter.

Used for disabling or enabling feedback in the application.

This is identical with the overload which has only one parameter, with the exception that one can disable audio and vibra feedback separately with this version.

Since:

S60 5.0

Parameters:

	aVibraEnabled	- Give ETrue as parameter for enabling vibra feedback, and EFalse for disabling vibra feedback for this application.
	aAudioEnabled	- Give ETrue as parameter for enabling audio feedback, and EFalse for disabling audio feedback for this application.

Used for disabling or enabling feedback in the application.

Tactile feedback is enabled by default, and thus standard S60 components (such as CBA, lists and options menu) automatically give feedback even if the application itself would make no effort for producing feedback.

For some applications (such as games) feedback might not be wanted at all. In addition some applications may need to disable feedback in some specific situations. For example: A camera application may need to disable feedback during video recording, because otherwise feedbacks may cause disturbing sounds that will be recorded into the video clip.

Notice that this function only affects direct feedback and area registry based feedback for this application. I.e. if this application is taken to background, other applications can still produce feedback.

Also notice that enabling feedback doesn't still mean that feedback would necessarily be generated, because user may have disabled the feedback for whole device from the settings.

Since:

S60 5.0

Parameters:

aEnabled

- Give ETrue as parameter for enabling feedback, and EFalse for disabling feedback.

This function can be used to check, whether touch feedback is supported at all in the device.

All the API functions can be called safely even if touch feedback is not enabled (for e.g. in devices without touch screen). But in some situations registry updates can require complex calculations, which can be skipped if touch feedback is not enabled at all.

Notice that the settings related to touch feedback have no effect on the behavior of this function. I.e. even if user turns touch feedback OFF from settings, this function still returns ETrue. The reason for this is that registry updates must be done anyway even if the feedback is not on for the moment, because user can turn it on at anytime, and it is not possible to force an update for all applications in that case.

Since:

S60 5.0

Returns:

ETrue if touch feedback is supported in this device.