1 /*

     2 * Copyright (c) 2006 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 "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:   Event class.

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef T_ALFEVENT_H

    21 #define T_ALFEVENT_H

    22 

    23 #include <w32std.h>

    24 #include <alf/alfscrollerevent.h>

    25 

    26 class CAlfDisplay;

    27 class CAlfVisual;

    28 

    29 /**

    30  *  Event class.

    31  *  This class would typically be passed to a control.

    32  *  One example of an event would be a keypress,

    33  *  or a custom message arriving from another control.

    34  *  You cannot derive from this class.

    35  *  Usage:

    36  *  A custom control, derived from Control, overwrides, OfferEventL()

    37  *  @code

    38  *  TBool LayoutControl::OfferEventL(const TAlfEvent& aEvent)

    39  *  {

    40  * 	TBool handled = EFalse;

    41  *  if ( aEvent.IsKeyEvent() )

    42  *       {

    43  *        / Do something

    44  *        handled = ETrue;         

    45  *       }

    46  *   else if ( aEvent.IsPointerEvent() )

    47  *        {

    48  *         switch ( aEvent.PointerEvent().iType )

    49  *           {

    50  *           case TPointerEvent::EButton1Down:

    51  *              / Do something

    52  *               break;

    53  *           case TPointerEvent::EButton1Up:

    54  *               / Do something

    55  *               break;

    56  *           case TPointerEvent::EDrag:

    57  *              / Do something

    58  *               break;

    59  *           case TPointerEvent::EButtonRepeat:

    60  *               / Do something

    61  *               break;

    62  *           default:

    63  *              / Do something

    64  *               break;

    65  * 			 }

    66  *          handled = ETrue;

    67  *       }

    68  *    }

    69  *  @endcode

    70  *  @see MAlfEventHandler::OfferEventL()

    71  *  @lib alfclient.lib

    72  *  @since S60 v3.2

    73  */

    74 NONSHARABLE_CLASS( TAlfEvent )

    75     {

    76     

    77 public:

    78 

    79     /** Event types. This is the most general type for the message.*/

    80     enum TType

    81         {

    82         ETypeCustom, 		//!< a message passed from one control to another

    83         ETypeKey,			//!< a message regarding a keypress

    84         ETypePointer,		//!< a message regarding a touch screen interface

    85         ETypeIdleBegin,	    //!< the toolkit has just entered the idle state

    86         ETypeIdleEnd,		//!< the toolkit has just left the idle state

    87         ETypeScroller,	    //!< a message sent from a scroller

    88         

    89         EAlfEventTypeLast = 1024

    90         };

    91         

    92     /* Constructors. */

    93    

    94     /**

    95      * Constructor.

    96      */

    97     TAlfEvent(CAlfDisplay& aDisplay, TType aType);

    98     

    99     /**

   100      * Constructor for custom events (not bound to any display).

   101      */

   102     IMPORT_C TAlfEvent(TInt aCustomParam);

   103 

   104     /**

   105      * Constructor for custom events (not bound to any display).

   106      */

   107     IMPORT_C TAlfEvent(TInt aCustomParam, TInt aCustomEventData);

   108    

   109     /**

   110      * Constructor for scroller event bound to a display.

   111      */

   112     IMPORT_C TAlfEvent(CAlfDisplay&, const TAlfScrollerEvent& aEvent );

   113    

   114     /**

   115      * Constructor for key events.

   116      *

   117      * @param aDisplay Display where the event is received

   118      * @param aKeyEvent Key event definition

   119      * @param aType Event code

   120      */

   121     IMPORT_C TAlfEvent(CAlfDisplay& aDisplay, const TKeyEvent& aKeyEvent, TEventCode aType);

   122 

   123     /**

   124      * Constructor for pointer events.

   125      *

   126      * @param aDisplay Display where the event is received

   127      * @param aPointerEvent Pointer event definition

   128      *          iPosition Contains the coordinates relative to the hit visual

   129      *          iParentPosition Contains the coordinates relative to the used display area.

   130      */

   131     IMPORT_C TAlfEvent(CAlfDisplay& aDisplay, const TPointerEvent& aPointerEvent );

   132     

   133     /**

   134      * Determines whether the event is a pointer event.

   135      *

   136      * @todo needs more description

   137      * @return ETrue if pointer event.

   138      */

   139     IMPORT_C TBool IsPointerEvent() const;

   140     

   141     /**

   142      * Returns pointer event. Panics is not pointer event.

   143      *

   144      * On the stylus up and down events, the hit leaf visual can be fetched with

   145      * Visual() function. If the function returns a visual, the iPosition member

   146      * variable of the TPointerEvent states the event coordinates relative to that 

   147      * visual area. If the visual is not found, the iPosition is the same as iParentPosition.

   148      *

   149      * The iParentPosition memeber variable of the TPointerEvent states the event

   150      * coordinates relative to the used display visible area. See, that this is usually

   151      * the main pane area and not the physical screen dimensions.

   152      *

   153      * The iParentPosition coornidates can be mapped to any visual's local coordinates by

   154      * visual->DisplayToLocal( aEvent.PointerEvent().iParentPosition );

   155      *

   156      * If the visual is set, the following applies:

   157      * aEvent.Visual()->LocalToDisplay( aEvent.PointerEvent().iPosition ) == aEvent.PointerEvent().iParentPosition

   158      * aEvent.Visual()->DisplayToLocal( aEvent.PointerEvent().iParentPosition ) == aEvent.PointerEvent().iPosition

   159      *

   160      * @return Pointer event.

   161      */

   162     IMPORT_C const TPointerEvent& PointerEvent() const;

   163 

   164     /**

   165      * Returns the type of the event.

   166      * @see TType

   167      */     

   168     IMPORT_C TType Type() const;

   169     

   170     /**

   171      * Determines whether the event is a custom event.

   172      */     

   173     IMPORT_C TBool IsCustomEvent() const;

   174 

   175     /**

   176      * Returns whether the event is a scroller event.

   177      *

   178      * @return EFalse iff the event is not a scroller event

   179      */     

   180     IMPORT_C TBool TAlfEvent::IsScrollerEvent() const;

   181 

   182     /**

   183      * Access an ALF scroller event object. 

   184      *

   185      * Only can be called if IsScrollerEvent() is not EFalse

   186      *

   187      * @return a structure containing the scroller event

   188      */

   189     IMPORT_C TAlfScrollerEvent ScrollerEvent() const;

   190     

   191     /**

   192      * Determines whether the event is a key event, for example, a key was pressed.

   193      *

   194      * @return ETrue is key event.

   195      */ 

   196     IMPORT_C TBool IsKeyEvent() const;

   197     

   198     /**

   199      * Returns key event code. Panics if not key event.

   200      *

   201      * @return Key event code.

   202      */

   203     IMPORT_C const TEventCode& Code() const;

   204     

   205     /**

   206      * Returns key event. Panics if not key event.

   207      *

   208      * @return Key event.

   209      */

   210     IMPORT_C const TKeyEvent& KeyEvent() const;

   211     

   212     /**

   213      * Returns custom paramter. Panics if not custom event.

   214      *

   215      * @return Custom parameter.

   216      */

   217     IMPORT_C TInt CustomParameter() const;

   218     

   219     /**

   220      * Returns additional custom event data. Panics if not a custom event.

   221      * This can be either an identifier to find out the actual event data or

   222      * it can contain the data directly.

   223      *

   224      * @return Custom event data.

   225      */

   226     IMPORT_C TInt CustomEventData() const;    

   227     

   228     /**

   229      * Sets display

   230      *

   231      * @param aDisplay New display. Ownership not transferred.

   232      */

   233     void SetDisplay( CAlfDisplay* aDisplay );

   234     

   235     /**

   236     * Returns the display that the event comes from, if any.

   237     * NULL is returned if the event has not had a display set.  Custom events are

   238     * likely not to have a display set. Key events may have a display set 

   239     *

   240     * @return The display the event is associated with

   241     */

   242     IMPORT_C CAlfDisplay* Display() const;

   243     

   244     /**

   245      * Pointer is down.

   246      * @return ETrue if this is a pointer event and the pointer has been pressed down.

   247      */

   248     IMPORT_C TBool PointerDown() const;

   249 

   250     /**

   251      * Pointer is up.

   252      * @return ETrue if this is a pointer event and the pointer has been lifted up.

   253      */

   254     IMPORT_C TBool PointerUp() const;

   255     

   256     /**

   257      * Pointer event is a long press.

   258      * @return ETrue if this is a pointer event and the pointer has been pressed for long tap duration.

   259      */

   260     IMPORT_C TBool PointerLongTap() const;

   261     

   262     /**

   263      * Sets visual associated with the event

   264      *

   265      * @param aVisual Associated visual.

   266      */

   267     IMPORT_C void SetVisual(CAlfVisual* aVisual);

   268     

   269     /**

   270      * Returns visual associated with the event

   271      *

   272      * @return Associated visual. NULL if not set.

   273      */

   274     IMPORT_C CAlfVisual* Visual() const;

   275 

   276 private: // data

   277 

   278     /** The display from where the event originated. */

   279     CAlfDisplay* iDisplay;

   280 

   281     /** Type of this event, if it is a Symbian S60 event code.

   282     *

   283     * For example: EEventKeyUp, EEventKeyDown

   284     *

   285     * @see Symbian event codes.

   286     */    

   287     TEventCode iCode;

   288 

   289     /** The S60 struct that contains scancode, key event information, etc.

   290     * @see Symbian event codes.

   291     */        

   292     TKeyEvent iKeyEvent;

   293 

   294     /** The S60 struct that contains pointer device event info, which would be

   295     * triggered by touch screen interaction.

   296     * @see Symbian event codes.

   297     */            

   298     TAdvancedPointerEvent iPointerEvent;

   299     

   300     /**

   301      * Holds an alf scroller event object

   302      */

   303     TAlfScrollerEvent iScrollerEvent;

   304        

   305     /** Parameter for custom events. */

   306     TInt iParam;

   307     

   308     /** Additional event data for custom events. */

   309     TInt iCustomEventData;

   310 

   311     /** Type of the event. */

   312     TType iType;

   313     

   314     /** Visual which the event is associated with. */

   315     CAlfVisual* iVisual;

   316 

   317 private:

   318     // Advanced pointer event occupies the extra space

   319     //TInt iSpare1;

   320     //TInt iSpare2;

   321     };

   322 

   323 

   324 

   325 #endif // T_ALFEVENT_H