/*

* Copyright (c) 2006 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: 

*

*/

#ifndef AKNINPUTBLOCK_H

#define AKNINPUTBLOCK_H

#include <coecntrl.h>

#include <eikcmobs.h>

// FORWARD DECLARATIONS

class CEikButtonGroupContainer;

class CEikAppUi;

/**

 * MAknInputBlockCancelHandler is an interface to an object that

 * can handle the UI framework attempting to cancel a CAknInputBlock.

 * @since 3.1

 */

class MAknInputBlockCancelHandler

	{

public:

	virtual void AknInputBlockCancel() = 0;

	};

/**

 * CAknInputBlock blocks user input, key and pen, from reaching

 * existing controls, such as softkeys, dialogs or main panes.

 * It will not block controls higher on the control stack than

 * ECoeStackPriorityDialog.

 * It will not block subsequently created dialogs.

 * It will detect attempts from the UI framework to cancel the 

 * blocked state.

 * Clients should supply something to handle such cancel requests.

 * There are three ways that cancel can be signalled: through

 * an M-class interface, by cancelling an active object, by

 * deleting a CBase derived object.

 * All three cancel methods can be active. When a cancel signal

 * is detected, the handlers will be triggered in the order of

 * M-class first, then active object cancel, finally CBase delete.

 * If no cancel hander is supplied, all input is blocked, including

 * framework attempts to deactivate views and exit the application.

 *

 * This is an example of use of all cancel methods with an active object that

 * blocks with a CActiveSchedulerWait...

 * CAknInputBlock* inputBlock = CAknInputBlock::NewCancelHandlerLC(this);	// notify "this" on cancel

 * CAOWait* wait = CAOWait::NewL();			// create waiting active object

 * inputBlock->SetCancelActive(wait);		// set it as an active object to cancel

 * inputBlock->SetCancelDelete(wait);		// set it as an object to delete, takes ownership

 * wait->Start();

 * inputBlock->SetCancelHandler(NULL);		// Clear the cancel handler so that "this" is not notified by cancel on deletion

 * CleanupStack::PopAndDestroy(inputBlock);	// wait will be cancelled and deleted by inputBlock

 *

 * @since 3.1

 */

NONSHARABLE_CLASS(CAknInputBlock) : public CCoeControl, public MEikCommandObserver

	{

public:

    /**

    * Create a new input blocker with no cancel support.

    * Cancel handling can be set later with one of the

    * SetCancel... methods.

    * Note: while this object exists without cancel support,

    * view deactivations and application exit requests will not be processed.

    * @return a new instance of CAknInputBlock on the cleanup stack

    */

	IMPORT_C static CAknInputBlock* NewLC();

    /**

    * Create a new input blocker with M-class cancel support.

    * @param aHandlerToCancel, a pointer to the M-class instance

    * to call back on cancel. Does not take ownership. Can be

    * called with NULL to clear the cancel handler.

    * @return a new instance of CAknInputBlock on the cleanup stack

    */

	IMPORT_C static CAknInputBlock* NewCancelHandlerLC(MAknInputBlockCancelHandler* aHandlerToCancel);

    /**

    * Create a new input blocker with active object cancel support.

    * @param aActiveObjectToCancel, a pointer to the active object

    * to cancel. Does not take ownership. Can be called with

    * NULL to clear the cancel handler.

    * @return a new instance of CAknInputBlock on the cleanup stack

    */

	IMPORT_C static CAknInputBlock* NewCancelActiveLC(CActive* aActiveObjectToCancel);

    /**

    * Create a new input blocker with object delete cancel support.

    * @param aObjectToDelete, a pointer to the CBase-derived object

    * to delete on cancel. Take ownership. Can be called with

    * NULL to clear the cancel handler.

    * @return a new instance of CAknInputBlock on the cleanup stack

    */

	IMPORT_C static CAknInputBlock* NewCancelDeleteLC(CBase* aObjectToDelete);

	/**

	* destructor

	* This will also call Cancel()

	*/

	IMPORT_C ~CAknInputBlock();

	/**

	* Set a cancel handler.

    * @param aHandlerToCancel, a pointer to the M-class instance

    * to call back on cancel. Does not take ownership. Can be

    * called with NULL to clear the cancel handler.

	*/

	IMPORT_C void SetCancelHandler(MAknInputBlockCancelHandler* aHandlerToCancel);

	/**

	* Set a cancel handler.

    * @param aActiveObjectToCancel, a pointer to the active object

    * to cancel. Does not take ownership. Can be called with

    * NULL to clear the cancel handler.

	*/

	IMPORT_C void SetCancelActive(CActive* aActiveObjectToCancel);

	/**

	* Set a cancel handler.

    * @param aObjectToDelete, a pointer to the CBase-derived object

    * to delete on cancel. Take ownership. Can be called with

    * NULL to clear the cancel handler.

	*/

	IMPORT_C void SetCancelDelete(CBase* aObjectToDelete);

	/**

	* Called when the UI framework wants to cancel this input

	* blocking state, eg on app exit.

	* May also be called manually to force cancel.

	* After cancelling, all handers are set to NULL.

	*/

	IMPORT_C void Cancel();

private:

	CAknInputBlock();

	void ConstructL();

	bool IsCancellable() const;

private: // from CCoeControl

    TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent, TEventCode aType);

	void FocusChanged(TDrawNow aDrawNow);

private: // from MEikCommandObserver

	void ProcessCommandL(TInt /*aCommandId*/);

private:

	MAknInputBlockCancelHandler* iHandlerToCancel;	// not owned

	CActive* iActiveObjectToCancel;					// not owned

	CBase* iObjectToDelete;							// owned

	CEikAppUi* iAppUi;								// not owned

	CEikButtonGroupContainer* iCba;					// owned

	};

#endif