/*
* Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:  Application UI class
*  Version     : %version: 2 % << Don't touch! Updated by Synergy at check-out.
*/
#ifndef HNITEMFOCUSHANDLER_H
#define HNITEMFOCUSHANDLER_H

#include <e32base.h>
#include <e32std.h>

class CHnSuiteModel;

/**
 *  Class representing the focus item to be queued.
 *
 *  @lib hnpresentationmodel
 *  @since S60 5.0
 *  @ingroup group_hnpresentationmodel
 */
class TFocusQueueItem
	{
public:
	
    /**
     * Constructor. Sets the trigger time on construction.
     * 
     * @since S60 v5.0
     * @param aItemId Index of the item in the suite model.
     */
	TFocusQueueItem( TInt aItemId, TInt aEventId );
	
    /**
     * Fetches the focus item trigger time.
     * 
     * @since S60 v5.0
     * @return Time when the event was triggered.
     */
	TTime TriggerTime();
	
    /**
     * Fetches the focus/unfocus item id.
     * 
     * @since S60 v5.0
     * @return Suite model item id of the focused/unfocused item.
     */
	TInt ItemId();
	
    /**
     * Fetches the focus/unfocus item id.
     * 
     * @since S60 v5.0
     * @return Suite model item id of the focused/unfocused item.
     */
	TInt EventId();
	
    /**
     * Compares queued items by triggered time.
     * 
     * @since S60 v5.0
     * @param aItem1 First item to compare.
     * @param aItem2 Second item to compare.
     * @return 1 if aItem1 was triggered earlier than aItem2.
     * -1 if aItem1 was triggered later than aItem2.
     * 0 if aItem1 was triggered at the same time as aItem2.
     */
	static TInt CompareByTriggerTime( const TFocusQueueItem& aItem1,
			const TFocusQueueItem& aItem2 );
    /**
     * Compares queued items by triggered time.
     * 
     * @since S60 v5.0
     * @param aItem1 First item to compare.
     * @param aItem2 Second item to compare.
     * @return ETrue if aItem1 is equal to aItem2 regarding the item id.
     * EFalse if aItem1 is not equal to aItem2 regarding the item id.
     */
	static TBool CompareByItemId( const TFocusQueueItem& aItem1,
			const TFocusQueueItem& aItem2 );

private:
	
    /**
     * Item id.
     * Own.
     */
	TInt iItemId;
    
	/**
     * Trigger time.
     * Own.
     */
	TTime iTriggerTime;
    
	/**
     * Event type.
     */
	TInt iEventId;
	
	};

/**
 *  Item focus handler class.
 *
 *  This is an active object which handles focus/unfocus event triggering.
 *  This class causes focus/unfocus events to be run without performance impact
 *  on the UI. The focus/unfocus events are queued. If incoming events logically 
 *  cancel the queued events, the appropriate events are removed from the queue.
 *
 *  @lib hnpresentationmodel
 *  @since S60 5.0
 *  @ingroup group_hnpresentationmodel
 */
NONSHARABLE_CLASS( CHnItemFocusHandler ) : public CActive
	{
public:
	
    /**
    * Virtual Destructor.
    * 
    * @since S60 5.0
    */
	~CHnItemFocusHandler();

    /**
     * Two-phased constructor.
     * 
     * @since S60 5.0
     * @param aSuiteModel The suite model for which focus events are handled.
     */
	static CHnItemFocusHandler* NewL( CHnSuiteModel* aSuiteModel );

    /**
     * Two-phased constructor.
     * 
     * @since S60 5.0
     * @param aSuiteModel The suite model for which focus events are handled.
     */
	static CHnItemFocusHandler* NewLC( CHnSuiteModel* aSuiteModel );

public:
	
    /**
     * Called to initiate item focus action handling.
     * 
     * @since S60 v5.0
     * @param aEventId The type of event. Can be KIdFocusGain or KIdFocusLost. Otherwise focus actions are not triggered.
     * @param aItemId Index of the item in the suite model.
     */
	void SetFocusL( TInt aEventId, TBool aItemId );

private:
	
    /**
     * C++ default constructor.
     * 
     * @since S60 v5.0
     */
	CHnItemFocusHandler();

    /**
     * Second-phase constructor.
     * 
     * @since S60 v5.0
     * @param aSuiteModel The suite model for which focus events are handled.
     */
	void ConstructL( CHnSuiteModel* aSuiteModel );

private:
	
    /**
     * Handles completion. In fact the request is completed immediately after activating the object.
     * This method calls focus/unfocus action events.
     * 
     * @since S60 v5.0
     */
	void RunL();

    /**
     * Run when request is cancelled.
     */
	void DoCancel();

    /**
     * Overriden to handle leaves from RunL(). Default implementation causes
     * the active scheduler to panic.
     * 
     * @since S60 v5.0
     * @param aError The Error code.
     * @return Id The eroor code.
     */
	TInt RunError(TInt aError);
	
    /**
     * Removes duplicated items. E.g. if a request to focus an item has been triggered
     * when there is still a request to unfocus that item pending in the queue. Then the unfocus 
     * event will be removed from the queue and the event and only the focus event is triggered.
     * 
     * @since S60 v5.0
     * @param aFocusItem The item to be compared.
     * @param aEventId focus or unfocus event.
     */
	void RemoveDuplicatedItem( const TFocusQueueItem& aFocusItem );

private:
	
    /**
     * The suite model for which focus events are handled.
     * Not own.
     */
	CHnSuiteModel* iSuiteModel;
	
    /**
     * Focus Queue.
     * Own.
     */
	RArray<TFocusQueueItem> iFocusQueue;
	
	};

#endif // HNITEMFOCUSHANDLER_H