diff -r 666f914201fb -r 2fe1408b6811 epoc32/include/mw/touchfeedback.h --- a/epoc32/include/mw/touchfeedback.h Tue Nov 24 13:55:44 2009 +0000 +++ b/epoc32/include/mw/touchfeedback.h Tue Mar 16 16:12:26 2010 +0000 @@ -1,1 +1,521 @@ -touchfeedback.h +/* +* 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 +#include +#include + +#include + +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. + */ + virtual void EnableFeedbackForControl( const CCoeControl* aControl, + TBool aEnableVibra, + TBool aEnableAudio ) = 0; + + /** + * 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 + * @param aVibraEnabled - Give ETrue as parameter for enabling vibra + * feedback, and EFalse for disabling vibra + * feedback for this application. + * @param aAudioEnabled - Give ETrue as parameter for enabling audio + * feedback, and EFalse for disabling audio + * feedback for this application. + */ + virtual void SetFeedbackEnabledForThisApp( TBool aVibraEnabled, + TBool aAudioEnabled ) = 0; + }; + + + +#endif // M_TOUCHFEEDBACK_H