williamr@2: /* williamr@2: * Copyright (c) 2007-2008 Nokia Corporation and/or its subsidiary(-ies). williamr@2: * All rights reserved. williamr@2: * This component and the accompanying materials are made available williamr@4: * under the terms of "Eclipse Public License v1.0" williamr@2: * which accompanies this distribution, and is available williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html". williamr@2: * williamr@2: * Initial Contributors: williamr@2: * Nokia Corporation - initial contribution. williamr@2: * williamr@2: * Contributors: williamr@2: * williamr@2: * Description: Interface for using area registry and direct feedback from williamr@2: * applications and UI controls. williamr@4: * Part of: Tactile Feedback. williamr@2: * williamr@2: */ williamr@2: williamr@2: williamr@2: williamr@2: #ifndef M_TOUCHFEEDBACK_H williamr@2: #define M_TOUCHFEEDBACK_H williamr@2: williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: williamr@2: #include williamr@4: #include williamr@2: williamr@2: class CCoeControl; williamr@2: williamr@2: /** williamr@2: * This is the Tactile Feedback interface for UI Controls. williamr@2: * williamr@2: * Provides an interface to add, modify and remove feedback areas williamr@2: * in the registry. There is also an option to trigger direct feedback, williamr@2: * hence bypassing the registry. williamr@2: * williamr@2: * Feedback areas must always be related to some UI Control (derived williamr@2: * from CCoeControl). Areas are distinguished from each other based on williamr@2: * control's address and an index number (so that it is possible williamr@2: * to register and maintain multiple areas for same control). williamr@2: * williamr@2: * Clients must add, maintain and remove their feedback areas using this williamr@2: * API according to the state changes of the application / control, and williamr@2: * according to for e.g. device wide layout changes. williamr@2: * williamr@2: * There are two cases when tactile framework automatically updates the williamr@2: * feedback areas for control: Feedback is always disabled when control williamr@2: * becomes dimmed and re-enabled when control becomes undimmed again. williamr@2: * If control becomes invisible, then feedback areas are (temporarily) williamr@2: * removed, and they will be automatically added again when control williamr@2: * becomes visible again. williamr@2: * williamr@2: * This class is not intended for derivation outside the library. williamr@2: * williamr@2: * @lib touchfeedback.lib williamr@2: * @since S60 v5.0 williamr@2: */ williamr@2: class MTouchFeedback williamr@2: { williamr@2: public: williamr@2: williamr@2: /** williamr@2: * Used for acquiring a pointer to touch feedback instance. williamr@2: * williamr@2: * Pointer is retrieved from thread local storage, and thus it is best williamr@2: * to store the returned pointer as member variable in case it will williamr@2: * be needed frequently. williamr@2: * williamr@2: * NULL is returned in case there is no instance. In that case williamr@2: * CreateInstanceL -function can be used for creating a new instance. williamr@2: * williamr@2: * @since S60 5.0 williamr@2: * @return Pointer to touch feedback instance created for this williamr@2: * application process. williamr@2: */ williamr@2: IMPORT_C static MTouchFeedback* Instance(); williamr@2: williamr@2: /** williamr@2: * Creates a new touch feedback instance. The usage of williamr@2: * this function should only be necessary from processes which williamr@2: * are not GUI applications, but which still have user interface williamr@2: * (or want to play direct feedback). williamr@2: * williamr@2: * DestroyInstance -function must be called for deleting the instance williamr@2: * when it is no longer needed. williamr@2: * williamr@2: * @since S60 5.0 williamr@2: * @return Pointer to new touch feedback instance. williamr@2: */ williamr@2: IMPORT_C static MTouchFeedback* CreateInstanceL(); williamr@2: williamr@2: /** williamr@2: * Destroys the touch feedback instance and clears pointer in williamr@2: * thread local storage. williamr@2: * williamr@2: * This function must only be used in case touch feedback has been williamr@2: * created with CreateInstanceL -function. I.e. normal GUI applications williamr@2: * should never call this function. williamr@2: * williamr@2: * @since S60 5.0 williamr@2: */ williamr@2: IMPORT_C static void DestroyInstance(); williamr@2: williamr@2: /** williamr@2: * This function can be used to check, whether touch feedback is williamr@2: * supported at all in the device. williamr@2: * williamr@2: * All the API functions can be called safely even if touch feedback williamr@2: * is not enabled (for e.g. in devices without touch screen). But in williamr@2: * some situations registry updates can require complex calculations, williamr@2: * which can be skipped if touch feedback is not enabled at all. williamr@2: * williamr@2: * Notice that the settings related to touch feedback have no effect williamr@2: * on the behavior of this function. I.e. even if user turns touch williamr@2: * feedback OFF from settings, this function still returns williamr@2: * ETrue. The reason for this is that registry updates must be done williamr@2: * anyway even if the feedback is not on for the moment, because williamr@2: * user can turn it on at anytime, and it is not possible to force williamr@2: * an update for all applications in that case. williamr@2: * williamr@2: * @since S60 5.0 williamr@2: * @return ETrue if touch feedback is supported in this device. williamr@2: */ williamr@2: virtual TBool TouchFeedbackSupported() = 0; williamr@2: williamr@2: /** williamr@2: * Used for disabling or enabling feedback in the application. williamr@2: * williamr@2: * Tactile feedback is enabled by default, and thus standard williamr@2: * S60 components (such as CBA, lists and options menu) automatically williamr@2: * give feedback even if the application itself would make no effort williamr@2: * for producing feedback. williamr@2: * williamr@2: * For some applications (such as games) feedback might not be williamr@2: * wanted at all. In addition some applications may need to disable williamr@2: * feedback in some specific situations. For example: A camera williamr@2: * application may need to disable feedback during video recording, williamr@2: * because otherwise feedbacks may cause disturbing sounds that williamr@2: * will be recorded into the video clip. williamr@2: * williamr@2: * Notice that this function only affects direct feedback and williamr@2: * area registry based feedback for this application. I.e. if this williamr@2: * application is taken to background, other applications can still williamr@2: * produce feedback. williamr@2: * williamr@2: * Also notice that enabling feedback doesn't still mean that feedback williamr@2: * would necessarily be generated, because user may have disabled the williamr@2: * feedback for whole device from the settings. williamr@2: * williamr@2: * @since S60 5.0 williamr@2: * @param aEnabled - Give ETrue as parameter for enabling feedback, and williamr@2: * EFalse for disabling feedback. williamr@2: */ williamr@2: virtual void SetFeedbackEnabledForThisApp( TBool aEnabled ) = 0; williamr@2: williamr@2: /** williamr@2: * Used to check whether feedback is enabled for this application. williamr@2: * williamr@2: * Notice that this function only returns what was given as parameter williamr@2: * to SetFeedbackEnabledForThisApp -function. I.e. this function williamr@2: * can return ETrue even if feedback would be currently disabled williamr@2: * from settings. williamr@2: * williamr@2: * If only vibra or audio feedback is enabled, this function still williamr@2: * returns ETrue. williamr@2: * williamr@2: * @since S60 5.0 williamr@2: * @return ETrue if feedback is enabled for this application. williamr@2: */ williamr@2: virtual TBool FeedbackEnabledForThisApp() = 0; williamr@2: williamr@2: /** williamr@2: * Sets or updates rectangular feedback area to registry. williamr@2: * williamr@2: * If this is new area (i.e. there is not yet area with given control williamr@2: * address and area index in the registry), then this area will be williamr@2: * added as the top priority area for its window, i.e. this williamr@2: * area will be hit test first when pointer event arrives. williamr@2: * williamr@2: * Notice however, that this area will remain as top priority area only williamr@2: * until the next new area is added to the registry, or until williamr@2: * MoveFeedbackAreaToFirstPriority -function is called. I.e. new areas williamr@2: * are always put on top priority, but they will only remain on top williamr@2: * until they will be overridden by next area. williamr@2: * williamr@2: * The control that is given as parameter should usually be the one williamr@2: * that is responsible of handling the pointer events on the williamr@2: * corresponding feedback area. williamr@2: * williamr@2: * The area can later be identified by passing control pointer and williamr@2: * index as parameters to the other functions (for modifying or williamr@2: * removing the feedback area). In case control only williamr@2: * registers one area, then index 0 can always be used. Usually most williamr@2: * sensible approach is to use indexes 1, 2, 3 etc. for additional williamr@2: * feedback areas, but in practice any desired index values can be williamr@2: * used. williamr@2: * williamr@2: * Notice that if given control is dimmed, then feedback type will williamr@2: * be set to "None". If given control is not visible, then feedback williamr@2: * area will not be added to registry at all (for now). However, williamr@2: * registry is automatically updated when control's dimming or williamr@2: * visibility changes, so one can call this function also for williamr@2: * dimmed and invisible control. williamr@2: * williamr@2: * When the control given as parameter to this function is destroyed, williamr@2: * then the RemoveFeedbackForControl -function must be called while williamr@2: * giving the same control as parameter again. This is necessary williamr@2: * for removing all the feedback areas, and also for resetting the williamr@2: * state information stored by the API implementation. williamr@2: * williamr@2: * @since S60 5.0 williamr@2: * @param aControl - The control handling pointer events on this williamr@2: feedback area. williamr@2: * @param aIndex - The index number of the area to be added. williamr@2: * @param aRect - The feedback area rectangle. williamr@2: * @param aFeedbackType - The logical feedback type given williamr@2: * @param aEventType - The pointer event type that triggers the williamr@2: * feedback (currently only ETouchEventStylusDown williamr@2: * is supported). williamr@2: * @return KErrNone, or one of standard Symbian OS error codes williamr@2: * if setting of area to registry failed. williamr@2: * Some specific error codes: williamr@2: * KErrArgument - A NULL pointer was given as first parameter, or williamr@2: * the given control does not have any window williamr@2: * associated to it. williamr@2: * KErrNotSupported - Unsupported logical feedback type or williamr@2: * event type was given as parameter. williamr@2: */ williamr@2: virtual TInt SetFeedbackArea( const CCoeControl* aControl, williamr@2: TUint32 aIndex, williamr@2: TRect aRect, williamr@2: TTouchLogicalFeedback aFeedbackType, williamr@2: TTouchEventType aEventType ) = 0; williamr@2: williamr@2: /** williamr@2: * Removes feedback area from the registry. williamr@2: * williamr@2: * This function is designed to be used in case feedback areas williamr@2: * need to be removed elsewhere than in control's destructor. In williamr@2: * control's destructor RemoveFeedbackForControl -function must be williamr@2: * used instead. williamr@2: * williamr@2: * @since S60 5.0 williamr@2: * @param aControl - The control, who has registered the area. williamr@2: * @param aIndex - The index of the area to be removed. williamr@2: */ williamr@2: virtual void RemoveFeedbackArea( const CCoeControl* aControl, williamr@2: TUint32 aIndex ) = 0; williamr@2: williamr@2: /** williamr@2: * Removes all feedback areas of specified control from registry. williamr@2: * williamr@2: * This function also clears all related data that has been cached williamr@2: * by the API implementation, and thus it must always be called from williamr@2: * control's destructor in case control has used any of the following williamr@2: * functions: williamr@2: * - SetFeedbackArea williamr@2: * - EnableFeedbackForControl williamr@2: * williamr@2: * Especially notice that it is not enough to remove all feedback areas williamr@2: * individually by using RemoveFeedbackArea -function. williamr@2: * williamr@2: * The difference between this function and EnableFeedbackForControl williamr@2: * -function is that this function really removes all areas related williamr@2: * to this control from registry, whereas EnableFeedbackForControl williamr@2: * (when EFalse if given as parameter) only temporarily disables williamr@2: * those areas. williamr@2: * williamr@2: * @since S60 5.0 williamr@2: * @param aControl - Pointer to the control, whose area registry williamr@2: * entries and cached information will be removed. williamr@2: */ williamr@2: virtual void RemoveFeedbackForControl( const CCoeControl* aControl ) = 0; williamr@2: williamr@2: /** williamr@2: * Changes feedback area in the registry. williamr@2: * williamr@2: * The area must have been originally added to the registry with williamr@2: * SetFeedbackArea -function, or otherwise this function will williamr@2: * do nothing. williamr@2: * williamr@2: * This function is intended to be used especially in williamr@2: * portrait / landscape changes. williamr@2: * williamr@2: * If given CCoeControl pointer is NULL, then this function call williamr@2: * does nothing. williamr@2: * williamr@2: * @since S60 5.0 williamr@2: * @param aControl - The control, who has registered the area. williamr@2: * @param aIndex - The index number of the area, that will be changed. williamr@2: * @param aNewRect - New area rectangle for given feedback area. williamr@2: */ williamr@2: virtual void ChangeFeedbackArea( const CCoeControl* aControl, williamr@2: TUint32 aIndex, williamr@2: TRect aNewRect ) = 0; williamr@2: williamr@2: /** williamr@2: * Changes feedback type in the registry. williamr@2: * williamr@2: * Feedback can be temporarily disabled by giving ETouchFeedbackNone williamr@2: * as parameter (although using EnableFeedbackForControl function with williamr@2: * parameter EFalse is usually better for this functionality). williamr@2: * williamr@2: * The area must have been originally added to the registry with williamr@2: * SetFeedbackArea -function, or otherwise this function will williamr@2: * do nothing. williamr@2: * williamr@2: * If given control pointer is NULL, then this function call williamr@2: * is ignored. williamr@2: * williamr@4: * This function only changes feedback type for down event. williamr@4: * To change feedback types for all the events in the feedback area use williamr@4: * function SetFeedbackArea with CFeedbackSpec container class williamr@4: * definion instead. williamr@4: * williamr@2: * @since S60 5.0 williamr@2: * @param aControl - The control, who has registered the area. williamr@2: * @param aIndex - The index number of the area, that will be changed. williamr@2: * @param aNewType - New feedback type for the area. williamr@2: */ williamr@2: virtual void ChangeFeedbackType( const CCoeControl* aControl, williamr@2: TUint32 aIndex, williamr@2: TTouchLogicalFeedback aNewType ) = 0; williamr@2: williamr@2: williamr@2: /** williamr@2: * Makes the given feedback area the first priority area in the window williamr@2: * where it is located. williamr@2: * williamr@2: * In practice this means that this will be the first area that is williamr@2: * hit tested when a pointer event arrives. williamr@2: * williamr@2: * Notice however, that this area will only keep its top priority status williamr@2: * until the next area is added to the registry, or until williamr@2: * this function is called again for some other area. I.e. there is no williamr@2: * way for giving any area a permanent status as top priority area williamr@2: * (Registry works as a stack, and new items are added on top). williamr@2: * williamr@2: * If given control pointer is NULL, this function call does nothing. williamr@2: * williamr@2: * @since S60 5.0 williamr@2: * @param aControl - The control, who has registered the area. williamr@2: * @param aIndex - The index number of the area, which williamr@2: * will be prioritized. williamr@2: */ williamr@2: virtual void MoveFeedbackAreaToFirstPriority( const CCoeControl* aControl, williamr@2: TUint32 aIndex ) = 0; williamr@2: williamr@2: /** williamr@2: * This function forces all registry changes made on client side to be williamr@2: * sent to server side immediately. williamr@2: * williamr@2: * This operation causes always immediate and synchronous client-server williamr@2: * transaction, and can possibly also cause flushing of window server williamr@2: * client side buffer. Hence this function should only be used in case williamr@2: * there is a synchronization problem so that feedback triggered from williamr@2: * area registry does not correspond to the areas defined by application. williamr@2: * williamr@2: * This function is only likely to help in such situation, where this williamr@2: * application's active objects are running all the time for several seconds, williamr@2: * because in that case updates won't be transferred to server immediately. williamr@2: * williamr@2: * Calling this function has no effect in case there are no pending williamr@2: * area registry updates. williamr@2: * williamr@2: * @since S60 5.0 williamr@2: */ williamr@2: virtual void FlushRegistryUpdates( ) = 0; williamr@2: williamr@2: /** williamr@2: * Gives direct feedback. williamr@2: * williamr@2: * Notice that the feedback might not be actually played, if williamr@2: * for example user has disabled the feedback from the settings. williamr@2: * williamr@2: * This function always causes a synchronous client-server transaction, williamr@2: * and potentially flushing of window server client-side buffer. williamr@2: * williamr@2: * @since S60 5.0 williamr@2: * @param aType - The logical feedback type to play. williamr@2: */ williamr@2: virtual void InstantFeedback( TTouchLogicalFeedback aType ) = 0; williamr@2: williamr@2: /** williamr@2: * Gives direct feedback if given control has not disabled it. williamr@2: * williamr@2: * This function only gives feedback, if EnableFeedbackForControl williamr@2: * function has NOT been called on given control with second williamr@2: * parameter EFalse. williamr@2: * williamr@2: * This overload is recommended when williamr@2: * feedback is triggered from UI controls, because then the owner williamr@2: * of the control can decide whether both area registry based and williamr@2: * direct feedback should be enabled or not. williamr@2: * williamr@2: * If feedback is enabled for the given control, then this function williamr@2: * causes a synchronous client-server transaction, williamr@2: * and potentially flushing of window server client-side buffer. williamr@2: * williamr@2: * @since S60 5.0 williamr@4: * @param aControl - The control, who wishes to play feedback. williamr@2: * @param aType - The logical feedback type to play. williamr@2: */ williamr@2: virtual void InstantFeedback( const CCoeControl* aControl, williamr@2: TTouchLogicalFeedback aType ) = 0; williamr@2: williamr@2: williamr@2: /** williamr@2: * Can be used for querying, whether given control has any feedback williamr@2: * areas registered. williamr@2: * williamr@2: * It does not matter whether the areas are disabled or enabled for williamr@2: * the moment. williamr@2: * williamr@2: * Notice that one should not usually call this function, as it williamr@2: * is always allowed to call for example RemoveFeedbackArea williamr@2: * -function without checking if the area really exists (this williamr@2: * is done internally in the API implementation anyway). williamr@2: * williamr@2: * @since S60 5.0 williamr@2: * @param aControl - Pointer to the control, whose feedback is williamr@2: * queried. williamr@2: * @return ETrue if the given control has at least one feedback williamr@2: * area defined. EFalse otherwise. williamr@2: */ williamr@2: virtual TBool ControlHasFeedback( const CCoeControl* aControl ) = 0; williamr@2: williamr@2: /** williamr@2: * Can be used for querying, whether given control has a feedback williamr@2: * area defined with given index number. williamr@2: * williamr@2: * It does not matter whether the areas are disabled or enabled for williamr@2: * the moment. williamr@2: * williamr@2: * Notice that one should not usually call this function, as it williamr@2: * is always allowed to call for example RemoveFeedbackArea williamr@2: * -function without checking if the area really exists (this williamr@2: * is done internally in the API implementation anyway). williamr@2: * williamr@2: * @since S60 5.0 williamr@2: * @param aControl - Pointer to the control, whose feedback is williamr@2: * queried. williamr@2: * @param aIndex - The index number of the area which is queried. williamr@2: * @return ETrue if the given control has a feedback area defined williamr@2: * with given index number. EFalse otherwise. williamr@2: */ williamr@2: virtual TBool ControlHasFeedback( const CCoeControl* aControl, williamr@2: TUint32 aIndex ) = 0; williamr@2: williamr@2: /** williamr@2: * This function enables or disables all feedback areas registered for williamr@2: * the given control. Disabling also affects to the overloaded version williamr@2: * of InstantFeedback -function, so that feedback is not played if williamr@2: * the control given as parameter has its feedback disabled. williamr@2: * williamr@2: * This function can be used for temporarily disabling williamr@2: * the feedback for some given control. Calling with second parameter williamr@2: * ETrue re-enables feedback areas, but it still does not williamr@2: * guarantee any feedback (control can be dimmed, invisible, of may not williamr@2: * even have any feedback areas registered). williamr@2: * williamr@2: * This function affects both vibra- and audio feedback. williamr@2: * williamr@2: * Any control that uses this function must call RemoveFeedbackForControl williamr@2: * -function in its destructor. williamr@2: * williamr@2: * @since S60 5.0 williamr@2: * @param aControl - Pointer to control, whose feedback will be williamr@2: * enabled or disabled according to second parameter. williamr@2: * @param aEnable - Use EFalse for temporary disabling the feedback for williamr@2: * this control, and ETrue for restoring the situation williamr@2: * to normal. williamr@2: */ williamr@2: virtual void EnableFeedbackForControl( const CCoeControl* aControl, williamr@2: TBool aEnable ) = 0; williamr@2: williamr@2: /** williamr@2: * This function can be used for separately enabling or disabling audio- williamr@2: * and vibra feedback for the given control. williamr@2: * williamr@2: * Otherwise the function behaves in the same way as the overload with williamr@2: * only one TBool parameter. williamr@2: * williamr@2: * Any control that uses this function must call RemoveFeedbackForControl williamr@2: * -function in its destructor. williamr@2: * williamr@2: * @since S60 5.0 williamr@2: * @param aControl - Pointer to control, whose audio- and vibra williamr@2: * feedback will be enabled or disabled according williamr@2: * to given parameters. williamr@2: * @param aEnableVibra - Use EFalse for temporary disabling the vibra williamr@2: * feedback for this control, and ETrue for williamr@2: * restoring the situation to normal. williamr@2: * @param aEnableAudio - Use EFalse for temporary disabling the audio williamr@2: * feedback for this control, and ETrue for williamr@2: * restoring the situation to normal. williamr@2: */ williamr@2: virtual void EnableFeedbackForControl( const CCoeControl* aControl, williamr@2: TBool aEnableVibra, williamr@2: TBool aEnableAudio ) = 0; williamr@2: williamr@2: /** williamr@4: * Used for disabling/enabling audio/vibra feedback in williamr@4: * the application. williamr@2: * williamr@2: * This is identical with the overload which has only one parameter, williamr@2: * with the exception that one can disable audio and vibra feedback williamr@2: * separately with this version. williamr@2: * williamr@2: * @since S60 5.0 williamr@2: * @param aVibraEnabled - Give ETrue as parameter for enabling vibra williamr@2: * feedback, and EFalse for disabling vibra williamr@2: * feedback for this application. williamr@2: * @param aAudioEnabled - Give ETrue as parameter for enabling audio williamr@2: * feedback, and EFalse for disabling audio williamr@2: * feedback for this application. williamr@2: */ williamr@2: virtual void SetFeedbackEnabledForThisApp( TBool aVibraEnabled, williamr@4: TBool aAudioEnabled ) = 0; williamr@4: williamr@4: williamr@4: /** williamr@4: * Used to check whether audio or vibra feedback is enabled for this application. williamr@4: * williamr@4: * Notice that this function only returns what was given as parameter williamr@4: * to SetFeedbackEnabledForThisApp -function. I.e. this function williamr@4: * can return ETrue even if feedback would be currently disabled williamr@4: * from settings. williamr@4: * williamr@4: * @since S60 5.2 williamr@4: * @param aFeedbackType - Feedback type. williamr@4: * @return ETrue if asked feedback type is enabled for this application. williamr@4: */ williamr@4: virtual TBool FeedbackEnabledForThisApp( TTouchFeedbackType aFeedbackType ) = 0; williamr@4: williamr@4: /** williamr@4: * Starts continuous feedback if given control has not disabled it. williamr@4: * williamr@4: * Only one continuous feedback per control can be played simultaneously. williamr@4: * Started feedback will be stopped automatically if application loses williamr@4: * key focus or application crashes or some other control starts williamr@4: * continuous feedback. williamr@4: * williamr@4: * If StartFeedback is called again for the same control, then feedback williamr@4: * type and intensity are modified accordingly. This may cause a break williamr@4: * in the feedback effect in case feedback type changes. williamr@4: * williamr@4: * EnableFeedbackForControl also affects to this function so that williamr@4: * feedback is not given if EnableFeedbackForControl williamr@4: * function has been called with second and third parameter EFalse. williamr@4: * williamr@4: * @since S60 5.2 williamr@4: * @param aControl - The control, who wishes to play feedback. williamr@4: * @param aType - The continuous feedback type to play. williamr@4: * @param aPointerEvent - Pointer event which triggered this feedback williamr@4: * (give NULL as parameter if no related pointer williamr@4: * event available) williamr@4: * @param aIntensity - Feedback intensity to begin with. range 0-100%. williamr@4: * Use 50% if no reason to use other value. williamr@4: * @param aTimeout - Timeout value to automatically stop continuous williamr@4: * feedback if there's no new Start call within the williamr@4: * timeout. Use value 0 if timeout is not used. williamr@4: */ williamr@4: virtual void StartFeedback( const CCoeControl* aControl, williamr@4: TTouchContinuousFeedback aType, williamr@4: const TPointerEvent* aPointerEvent, williamr@4: TInt aIntensity, williamr@4: TTimeIntervalMicroSeconds32 aTimeout ) = 0; williamr@4: williamr@4: williamr@4: /** williamr@4: * This function modifies intensity of continuous feedback on the fly. williamr@4: * williamr@4: * @since S60 5.2 williamr@4: * @param aControl - The control which continuous feedback is modified. williamr@4: * @param aIntensity - New intensity value. range 0-100% williamr@4: */ williamr@4: virtual void ModifyFeedback( const CCoeControl* aControl, williamr@4: TInt aIntensity ) = 0; williamr@4: williamr@4: williamr@4: /** williamr@4: * This function stops continuous feedback. williamr@4: * williamr@4: * @since S60 5.2 williamr@4: * @param aControl - The control which continuous feedback is stopped. williamr@4: */ williamr@4: virtual void StopFeedback( const CCoeControl* aControl ) = 0; williamr@4: williamr@4: williamr@4: /** williamr@4: * This function enables or disables audio or/and vibra feedback in williamr@4: * whole device. williamr@4: * williamr@4: * Tactile feedback is enabled by default, and thus standard williamr@4: * S60 components (such as CBA, lists and options menu) automatically williamr@4: * give feedback even if the application itself would make no effort williamr@4: * for producing feedback. williamr@4: * williamr@4: * Requires WriteDeviceData capability williamr@4: * williamr@4: * @since S60 5.2 williamr@4: * @param aFeedbackType - Feedback types to be enabled/disabled defined as williamr@4: * a bitmask combination of enumeration items from williamr@4: * TTouchFeedbackType williamr@4: * @return KErrNone, or one of standard Symbian OS error codes williamr@4: * if user has not WriteDeviceData capability. williamr@4: */ williamr@4: virtual TInt SetFeedbackEnabledForDevice( TTouchFeedbackType aFeedbackType ) = 0; williamr@4: williamr@4: williamr@4: /** williamr@4: * Used to check enabled feedback types for the device. williamr@4: * williamr@4: * Notice that this function only returns what was given as parameter williamr@4: * to SetFeedbackEnabledForDevice -function. I.e. this function williamr@4: * can return ETrue even if feedback would be currently disabled williamr@4: * from settings. williamr@4: * williamr@4: * @since S60 5.2 williamr@4: * @return Enabled/disabled feedback types as bitmask combination. williamr@4: */ williamr@4: virtual TTouchFeedbackType FeedbackEnabledForDevice() = 0; williamr@4: williamr@4: williamr@4: /** williamr@4: * Gives direct feedback if given control has not disabled it. williamr@4: * williamr@4: * This overload is recommended when triggered feedback is related williamr@4: * to pointer event. System uses aPointerEvent to avoiding williamr@4: * two (or more) direct feedbacks for the same pointer event. williamr@4: * williamr@4: * @since S60 5.2 williamr@4: * @param aControl - The control, who wishes to play feedback. williamr@4: * @param aType - The logical feedback type to play. williamr@4: * @param aPointerEvent - pointer event which triggered this feedback. williamr@4: */ williamr@4: virtual void InstantFeedback( const CCoeControl* aControl, williamr@4: TTouchLogicalFeedback aType, williamr@4: const TPointerEvent& aPointerEvent ) = 0; williamr@4: williamr@4: williamr@4: /** williamr@4: * Sets or updates rectangular feedback area to registry. williamr@4: * williamr@4: * This overload allows user to set more than one touch event types to williamr@4: * one feedback area. Otherwise the function behaves in the same way williamr@4: * as the overload with separated feedback type and event type parameters. williamr@4: * williamr@4: * @since S60 5.2 williamr@4: * @param aControl - The control handling pointer events on this williamr@4: * feedback area. williamr@4: * @param aIndex - The index number of the area to be added. williamr@4: * @param aRect - The feedback area rectangle. williamr@4: * @param aFeedbackSpec - The specification how this feedback area williamr@4: * triggers feedback for different touch events. williamr@4: * @return KErrNone, or one of standard Symbian OS error codes williamr@4: * if setting of area to registry failed. williamr@4: * Some specific error codes: williamr@4: * KErrArgument - A NULL pointer was given as first parameter, or williamr@4: * the given control does not have any window williamr@4: * associated to it. williamr@4: * KErrNotSupported - Unsupported predefined feedback profile williamr@4: * was given as parameter. williamr@4: */ williamr@4: virtual TInt SetFeedbackArea( const CCoeControl* aControl, williamr@4: TUint32 aIndex, williamr@4: TRect aRect, williamr@4: CFeedbackSpec* aFeedbackSpec ) = 0; williamr@4: williamr@4: /** williamr@4: * Gives direct feedback if given control has not disabled it. williamr@4: * williamr@4: * This overload is recommended when triggered feedback is related williamr@4: * to pointer event. System uses aPointerEvent to avoiding williamr@4: * two (or more) direct feedbacks for the same pointer event. Using this williamr@4: * overload it is also possible to disable unwanted feedback (vibra/audio) williamr@4: * by giving only wanted feedback type as parameter. williamr@4: * williamr@4: * @since S60 5.2 williamr@4: * @param aControl - The control, who wishes to play feedback. williamr@4: * @param aType - The logical feedback type to play. williamr@4: * @param aFeedbackType - Feedback types to be played as a bitmask williamr@4: * combination of enumeration items from williamr@4: * TTouchFeedbackType williamr@4: * @param aPointerEvent - Pointer event, which triggered this feedback. williamr@4: */ williamr@4: virtual void InstantFeedback( const CCoeControl* aControl, williamr@4: TTouchLogicalFeedback aType, williamr@4: TTouchFeedbackType aFeedbackType, williamr@4: const TPointerEvent& aPointerEvent ) = 0; williamr@4: williamr@4: williamr@4: williamr@2: }; williamr@2: williamr@2: williamr@2: williamr@2: #endif // M_TOUCHFEEDBACK_H