diff -r 000000000000 -r 2f259fa3e83a classicui_plat/input_block_api/inc/AknInputBlock.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/classicui_plat/input_block_api/inc/AknInputBlock.h Tue Feb 02 01:00:49 2010 +0200 @@ -0,0 +1,168 @@ +/* +* 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 +#include + +// 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