/*

* Copyright (c) 2007-2008 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

* which accompanies this distribution, and is available

* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:  Interface for using area registry and direct feedback from

*                applications and UI controls.

*

*/

#ifndef M_TOUCHFEEDBACK_H

#define M_TOUCHFEEDBACK_H

#include <e32std.h>

#include <e32base.h>

#include <coemain.h>

#include <touchlogicalfeedback.h>

class CCoeControl;

/**

 *  This is the Tactile Feedback interface for UI Controls.

 *

 *  Provides an interface to add, modify and remove feedback areas

 *  in the registry. There is also an option to trigger direct feedback, 

 *  hence bypassing the registry.

 *

 *  Feedback areas must always be related to some UI Control (derived

 *  from CCoeControl). Areas are distinguished from each other based on

 *  control's address and an index number (so that it is possible

 *  to register and maintain multiple areas for same control).

 *

 *  Clients must add, maintain and remove their feedback areas using this

 *  API according to the state changes of the application / control, and

 *  according to for e.g. device wide layout changes.

 *

 *  There are two cases when tactile framework automatically updates the

 *  feedback areas for control: Feedback is always disabled when control

 *  becomes dimmed and re-enabled when control becomes undimmed again.

 *  If control becomes invisible, then feedback areas are (temporarily)

 *  removed, and they will be automatically added again when control

 *  becomes visible again.

 *

 *  This class is not intended for derivation outside the library.

 *

 *  @lib touchfeedback.lib

 *  @since S60 v5.0

 */

class MTouchFeedback

    {

public:

    /**

     * 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

     * @return Pointer to touch feedback instance created for this

     *         application process.

     */

    IMPORT_C static MTouchFeedback* Instance();

    /**

     * 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

     * @return Pointer to new touch feedback instance.

     */

    IMPORT_C static MTouchFeedback* CreateInstanceL();

    /**

     * 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

     */

    IMPORT_C static void DestroyInstance();

    /**

     * 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

     * @return ETrue if touch feedback is supported in this device.

     */

    virtual TBool TouchFeedbackSupported() = 0;

    /**

     * 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

     * @param aEnabled - Give ETrue as parameter for enabling feedback, and

     *                   EFalse for disabling feedback.

     */

    virtual void SetFeedbackEnabledForThisApp( TBool aEnabled ) = 0;

    /**

     * 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

     * @return ETrue if feedback is enabled for this application.

     */

    virtual TBool FeedbackEnabledForThisApp() = 0;

    /**

     * 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

     * @param aControl      - The control handling pointer events on this

                              feedback area.

     * @param aIndex        - The index number of the area to be added.

     * @param aRect         - The feedback area rectangle.

     * @param aFeedbackType - The logical feedback type given

     * @param aEventType    - The pointer event type that triggers the 

     *                        feedback (currently only ETouchEventStylusDown

     *                        is supported).

     * @return 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.

     */

    virtual TInt SetFeedbackArea( const CCoeControl* aControl, 

                                  TUint32 aIndex,

                                  TRect aRect, 

                                  TTouchLogicalFeedback aFeedbackType, 

                                  TTouchEventType aEventType ) = 0;

    /**

     * 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

     * @param aControl - The control, who has registered the area.

     * @param aIndex   - The index of the area to be removed.

     */

    virtual void RemoveFeedbackArea( const CCoeControl* aControl, 

                                     TUint32 aIndex ) = 0;

    /**

     * 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

     * @param aControl - Pointer to the control, whose area registry 

     *                   entries and cached information will be removed.

     */

    virtual void RemoveFeedbackForControl( const CCoeControl* aControl ) = 0;

    /**

     * 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

     * @param aControl - The control, who has registered the area.

     * @param aIndex   - The index number of the area, that will be changed.

     * @param aNewRect - New area rectangle for given feedback area.

     */

    virtual void ChangeFeedbackArea( const CCoeControl* aControl, 

                                     TUint32 aIndex, 

                                     TRect aNewRect ) = 0;

    /**

     * 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

     * @param aControl - The control, who has registered the area.

     * @param aIndex   - The index number of the area, that will be changed.

     * @param aNewType - New feedback type for the area.

     */

    virtual void ChangeFeedbackType( const CCoeControl* aControl, 

                                     TUint32 aIndex, 

                                     TTouchLogicalFeedback aNewType ) = 0;

    /**

     * 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

     * @param aControl - The control, who has registered the area.

     * @param aIndex   - The index number of the area, which 

     *                   will be prioritized.

     */

    virtual void MoveFeedbackAreaToFirstPriority( const CCoeControl* aControl, 

                                                  TUint32 aIndex ) = 0;

    /**

     * 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

     */

    virtual void FlushRegistryUpdates( ) = 0;

    /**

     * 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

     * @param aType - The logical feedback type to play.

     */

    virtual void InstantFeedback( TTouchLogicalFeedback aType ) = 0;

    /**

     * 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

     * @param aControl - The control, who fishes to play feedback.

     * @param aType    - The logical feedback type to play.

     */

    virtual void InstantFeedback( const CCoeControl* aControl,

                                  TTouchLogicalFeedback aType ) = 0;

    /**

     * 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

     * @param aControl - Pointer to the control, whose feedback is

     *                   queried.

     * @return ETrue if the given control has at least one feedback

     *         area defined. EFalse otherwise.

     */

    virtual TBool ControlHasFeedback( const CCoeControl* aControl ) = 0;

    /**

     * 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

     * @param aControl - Pointer to the control, whose feedback is

     *                   queried.

     * @param aIndex   - The index number of the area which is queried.

     * @return ETrue if the given control has a feedback area defined

     *         with given index number. EFalse otherwise.

     */

    virtual TBool ControlHasFeedback( const CCoeControl* aControl, 

                                      TUint32 aIndex ) = 0;

    /**

     * 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

     * @param aControl - Pointer to control, whose feedback will be 

     *                   enabled or disabled according to second parameter.

     * @param aEnable  - Use EFalse for temporary disabling the feedback for

     *                   this control, and ETrue for restoring the situation

     *                   to normal.

     */

    virtual void EnableFeedbackForControl( const CCoeControl* aControl,

                                           TBool aEnable ) = 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

     * @param aControl - Pointer to control, whose audio- and vibra 

     *                   feedback will be enabled or disabled according 

     *                   to given parameters.

     * @param aEnableVibra  - Use EFalse for temporary disabling the vibra 

     *                        feedback for this control, and ETrue for 

     *                        restoring the situation to normal.

     * @param aEnableAudio  - Use EFalse for temporary disabling the audio 

     *                        feedback for this control, and ETrue for 

     *                        restoring the situation to normal.

     */