1 aknlongtapdetector.h

     1 /*

     2 * Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * 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

     6 * which accompanies this distribution, and is available

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

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Long Tap Detector with animation informing of long tap functionality

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef CAKNLONGTAPDETECTORCONTROLLER_H

    21 #define CAKNLONGTAPDETECTORCONTROLLER_H

    22 

    23 #include <w32std.h>

    24 #include <e32base.h>

    25 #include <coemain.h>

    26 

    27 /**

    28  * Avkon LongTapDetector CallBack.

    29  *

    30  * Inherit from this class and implement HandleLongTapEventL to

    31  * get a callback when/if a long tap occurs.

    32  *

    33  * @lib avkon.lib

    34  * @since S60 5.0

    35  */

    36 class MAknLongTapDetectorCallBack

    37     {

    38 public:

    39     /**

    40     * Callback method. Get's called when a long tap occurs.

    41     * @param aPenEventLocation Long tap event location relative to parent control.

    42     * @param aPenEventScreenLocation Long tap event location relative to screen.

    43     */

    44     virtual void HandleLongTapEventL( const TPoint& aPenEventLocation, 

    45                                       const TPoint& aPenEventScreenLocation ) = 0;

    46     };

    47 

    48 

    49 /**

    50  * Avkon Long Tap Detector. 

    51  *

    52  * Receives pointer events from owner application or owner control and returns

    53  * location if a long tap event occurs.

    54  * After short period of time (default 0,15s) animation is displayed next to stylus on the screen to

    55  * inform the user of long tap functionality. Animation can be turned OFF by application if wanted.

    56  *

    57  * @lib avkon.lib

    58  * @since S60 5.0

    59  */

    60 NONSHARABLE_CLASS( CAknLongTapDetector ) : public CTimer, MCoeMessageMonitorObserver

    61     {

    62 public: // Constructors and destructor	

    63 

    64     /**

    65      * Two-phased constructor.

    66      * @param aOwner Pointer to owner of this component. Ownership not transferred.

    67      */

    68     IMPORT_C static CAknLongTapDetector* NewL( MAknLongTapDetectorCallBack* aOwner );

    69 

    70     /**

    71      * Two-phased constructor.

    72      * @param aOwner Pointer to owner of this component. Ownership not transferred.

    73      */

    74     IMPORT_C static CAknLongTapDetector* NewLC( MAknLongTapDetectorCallBack* aOwner );

    75 

    76     /**

    77     * Destructor.

    78     */

    79     virtual ~CAknLongTapDetector();

    80 

    81 public: // New functions

    82 

    83     /**

    84     * Receives and handles pointer events from owner's HandlePointerEventL() -method.

    85     * Used to control timers in detecting long tap events.

    86     * @param aEvent Pointer event from owner.

    87     */

    88     IMPORT_C void PointerEventL( const TPointerEvent& aEvent );

    89 

    90     /**

    91     * Sets new time delay before long tap detector animation starts. Default delay is 0,15s.	

    92     * @param aMicroSeconds New delay in microseconds.

    93     */

    94     IMPORT_C void SetTimeDelayBeforeAnimation( const TInt aMicroSeconds );

    95 

    96     /**

    97     * Sets new time delay before long tap detector event is returned. Default delay is 0,8s.

    98     * @param aMicroSeconds New delay in microseconds.

    99     */

   100     IMPORT_C void SetLongTapDelay( const TInt aMicroSeconds );

   101 

   102     /**

   103     * Sets long tap animation ON/OFF. Default is ON.

   104     * @param aAnimation ETrue turns animations ON and EFalse turns animations OFF.

   105     */

   106     IMPORT_C void EnableLongTapAnimation( const TBool aAnimation );

   107 

   108     /**

   109     * Checks if the animation is running

   110     * @return ETrue if the animation is running, EFalse if not

   111     */

   112     IMPORT_C TBool IsAnimationRunning() const;

   113     

   114     /**

   115     * Cancels the long tap animation

   116     */

   117     IMPORT_C void CancelAnimationL();

   118 

   119 		/**

   120 		 * This function is used to capture key events during the longtap animation.

   121 		 * If such events are received, the longtap animation is then cancelled (TSW Error

   122 		 * ASAA-79TCJP).

   123 		 */

   124 		void MonitorWsMessage(const TWsEvent& aEvent);

   125 		

   126 private: // From CActive

   127 

   128     /**

   129     * Handles CTimer events. Called by system framework.

   130     */

   131     void RunL();

   132 

   133 private: // Constructors

   134 

   135     /**

   136     * C++ default constructor.

   137     * @param aOwner Owner.

   138     */

   139     CAknLongTapDetector( MAknLongTapDetectorCallBack* aOwner );

   140 

   141     /**

   142     * By default Symbian 2nd phase constructor is private.

   143     */

   144     void ConstructL();

   145 

   146 private: // New functions

   147 

   148     void StartAnimationL();

   149     void StopAnimationL();	

   150 

   151 private: // Data

   152 

   153     enum TLongTapDetectorState

   154         {

   155         EWaiting, 				// normal state

   156         EWaitingForAnimation,	// Only "Pen down" event received, CTimer started

   157         EShowingAnimation		// Long tap animation started

   158         };

   159 

   160     /**

   161     * Current state of LongTapDetector.

   162     */

   163     TLongTapDetectorState iState;

   164     

   165     /**

   166     * Pointer to owner of this LongTapDetector object.

   167     * Not own.

   168     */

   169     MAknLongTapDetectorCallBack* iOwner;

   170 

   171     /**

   172     * Delay before animation starts in microseconds.

   173     */

   174     TInt iTimeDelayBeforeAnimation;

   175 

   176     /**

   177     * Delay before long tap event is reported in microseconds.

   178     */

   179     TInt iLongTapDelay; 

   180 

   181     /**

   182     * Pointer event received from owner.

   183     */

   184     TPointerEvent iPointerEvent;

   185 

   186     /**

   187     * Is long tap animation shown or not.

   188     */

   189     TBool iShowAnimation;

   190     

   191     };

   192 

   193 #endif // CAKNLONGTAPDETECTOR_H

   194 

   195 

   196 // End of File