1 /*

     2 * Copyright (c) 2007 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:  Application UI class

    15 *  Version     : %version: 2 % << Don't touch! Updated by Synergy at check-out.

    16 */

    17 #ifndef HNITEMFOCUSHANDLER_H

    18 #define HNITEMFOCUSHANDLER_H

    19 

    20 #include <e32base.h>

    21 #include <e32std.h>

    22 

    23 class CHnSuiteModel;

    24 

    25 /**

    26  *  Class representing the focus item to be queued.

    27  *

    28  *  @lib hnpresentationmodel

    29  *  @since S60 5.0

    30  *  @ingroup group_hnpresentationmodel

    31  */

    32 class TFocusQueueItem

    33 	{

    34 public:

    35 	

    36     /**

    37      * Constructor. Sets the trigger time on construction.

    38      * 

    39      * @since S60 v5.0

    40      * @param aItemId Index of the item in the suite model.

    41      */

    42 	TFocusQueueItem( TInt aItemId, TInt aEventId );

    43 	

    44     /**

    45      * Fetches the focus item trigger time.

    46      * 

    47      * @since S60 v5.0

    48      * @return Time when the event was triggered.

    49      */

    50 	TTime TriggerTime();

    51 	

    52     /**

    53      * Fetches the focus/unfocus item id.

    54      * 

    55      * @since S60 v5.0

    56      * @return Suite model item id of the focused/unfocused item.

    57      */

    58 	TInt ItemId();

    59 	

    60     /**

    61      * Fetches the focus/unfocus item id.

    62      * 

    63      * @since S60 v5.0

    64      * @return Suite model item id of the focused/unfocused item.

    65      */

    66 	TInt EventId();

    67 	

    68     /**

    69      * Compares queued items by triggered time.

    70      * 

    71      * @since S60 v5.0

    72      * @param aItem1 First item to compare.

    73      * @param aItem2 Second item to compare.

    74      * @return 1 if aItem1 was triggered earlier than aItem2.

    75      * -1 if aItem1 was triggered later than aItem2.

    76      * 0 if aItem1 was triggered at the same time as aItem2.

    77      */

    78 	static TInt CompareByTriggerTime( const TFocusQueueItem& aItem1,

    79 			const TFocusQueueItem& aItem2 );

    80     /**

    81      * Compares queued items by triggered time.

    82      * 

    83      * @since S60 v5.0

    84      * @param aItem1 First item to compare.

    85      * @param aItem2 Second item to compare.

    86      * @return ETrue if aItem1 is equal to aItem2 regarding the item id.

    87      * EFalse if aItem1 is not equal to aItem2 regarding the item id.

    88      */

    89 	static TBool CompareByItemId( const TFocusQueueItem& aItem1,

    90 			const TFocusQueueItem& aItem2 );

    91 

    92 private:

    93 	

    94     /**

    95      * Item id.

    96      * Own.

    97      */

    98 	TInt iItemId;

    99     

   100 	/**

   101      * Trigger time.

   102      * Own.

   103      */

   104 	TTime iTriggerTime;

   105     

   106 	/**

   107      * Event type.

   108      */

   109 	TInt iEventId;

   110 	

   111 	};

   112 

   113 /**

   114  *  Item focus handler class.

   115  *

   116  *  This is an active object which handles focus/unfocus event triggering.

   117  *  This class causes focus/unfocus events to be run without performance impact

   118  *  on the UI. The focus/unfocus events are queued. If incoming events logically 

   119  *  cancel the queued events, the appropriate events are removed from the queue.

   120  *

   121  *  @lib hnpresentationmodel

   122  *  @since S60 5.0

   123  *  @ingroup group_hnpresentationmodel

   124  */

   125 NONSHARABLE_CLASS( CHnItemFocusHandler ) : public CActive

   126 	{

   127 public:

   128 	

   129     /**

   130     * Virtual Destructor.

   131     * 

   132     * @since S60 5.0

   133     */

   134 	~CHnItemFocusHandler();

   135 

   136     /**

   137      * Two-phased constructor.

   138      * 

   139      * @since S60 5.0

   140      * @param aSuiteModel The suite model for which focus events are handled.

   141      */

   142 	static CHnItemFocusHandler* NewL( CHnSuiteModel* aSuiteModel );

   143 

   144     /**

   145      * Two-phased constructor.

   146      * 

   147      * @since S60 5.0

   148      * @param aSuiteModel The suite model for which focus events are handled.

   149      */

   150 	static CHnItemFocusHandler* NewLC( CHnSuiteModel* aSuiteModel );

   151 

   152 public:

   153 	

   154     /**

   155      * Called to initiate item focus action handling.

   156      * 

   157      * @since S60 v5.0

   158      * @param aEventId The type of event. Can be KIdFocusGain or KIdFocusLost. Otherwise focus actions are not triggered.

   159      * @param aItemId Index of the item in the suite model.

   160      */

   161 	void SetFocusL( TInt aEventId, TBool aItemId );

   162 

   163 private:

   164 	

   165     /**

   166      * C++ default constructor.

   167      * 

   168      * @since S60 v5.0

   169      */

   170 	CHnItemFocusHandler();

   171 

   172     /**

   173      * Second-phase constructor.

   174      * 

   175      * @since S60 v5.0

   176      * @param aSuiteModel The suite model for which focus events are handled.

   177      */

   178 	void ConstructL( CHnSuiteModel* aSuiteModel );

   179 

   180 private:

   181 	

   182     /**

   183      * Handles completion. In fact the request is completed immediately after activating the object.

   184      * This method calls focus/unfocus action events.

   185      * 

   186      * @since S60 v5.0

   187      */

   188 	void RunL();

   189 

   190     /**

   191      * Run when request is cancelled.

   192      */

   193 	void DoCancel();

   194 

   195     /**

   196      * Overriden to handle leaves from RunL(). Default implementation causes

   197      * the active scheduler to panic.

   198      * 

   199      * @since S60 v5.0

   200      * @param aError The Error code.

   201      * @return Id The eroor code.

   202      */

   203 	TInt RunError(TInt aError);

   204 	

   205     /**

   206      * Removes duplicated items. E.g. if a request to focus an item has been triggered

   207      * when there is still a request to unfocus that item pending in the queue. Then the unfocus 

   208      * event will be removed from the queue and the event and only the focus event is triggered.

   209      * 

   210      * @since S60 v5.0

   211      * @param aFocusItem The item to be compared.

   212      * @param aEventId focus or unfocus event.

   213      */

   214 	void RemoveDuplicatedItem( const TFocusQueueItem& aFocusItem );

   215 

   216 private:

   217 	

   218     /**

   219      * The suite model for which focus events are handled.

   220      * Not own.

   221      */

   222 	CHnSuiteModel* iSuiteModel;

   223 	

   224     /**

   225      * Focus Queue.

   226      * Own.

   227      */

   228 	RArray<TFocusQueueItem> iFocusQueue;

   229 	

   230 	};

   231 

   232 #endif // HNITEMFOCUSHANDLER_H