/*

* Copyright (c) 2007 - 2008 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:  Base class for application states.

*

*/

#ifndef T_VTUIAPPSTATEBASE_H

#define T_VTUIAPPSTATEBASE_H

#include <e32base.h>

#include <mvtengsessioninfo.h>

#include "mvtuistatecontext.h"

#include "mvtuishutterobserver.h"

#include "tvtuistates.h"

/**

* Base class for application states related to application startup, normal

* operation and shutdown. AppUi delegates decision making by forwarding

* events/commands it receives to current state.

* Not all event handlers declared by the base class are applicable in

* all concrete states. All methods returning TEventResponse imply that it may

* consume the event completely and caller should not process it further.

*

* It should be kept in mind that as new functionality is added to application,

* state classes may need changes if e.g. handling of specific event should be

* allowed in appUi. By default event handler in specific state may consume all

* events. Note that in this context e.g. HandleCommandL is considered as an

* event handler.

*

* @since S60 v3.2

*/

class TVtUiAppStateBase : public MVtUiShutterObserver

    {

public: // new functions

    /**

    * Return value from state's event handlers.

    */

    enum TEventResponse

        {

        /** Event was handled by a state and should

         *  not be further processed by caller.

         */

        EEventHandled,

        /** Event can be handled by caller. */

        EEventNotHandled

    };

    /**

    * Performs state dependent actions when phase 1 of

    * startup is completed.

    */

    virtual void AppUiStartupPhase1DoneL();

    /**

    * Performs state dependent actions when startup fails.

    */

    virtual void AppUiStartupFailedL();

    /**

    * Performs state dependent actions when phase 2 of

    * startup is completed.

    */

    virtual void AppUiStartupPhase2DoneL();

    /**

    * Handles completion of shutdown.

    */

    virtual void ShutdownDoneL();

    /**

    * Handles completion of an VT engine command.

    * @param aCommand completed command

    * @param aError error

    * @return event response, is caller allowed to handle event

    */

    virtual TEventResponse HandleVTCommandPerformedL(

        const TVtEngCommandId aCommand,

        const TInt aError );

    /**

    * Handles event from the engine.

    * @param aEvent

    * @return event response, is caller allowed to handle event

    */

    virtual TEventResponse HandleVtEventL( const TInt aEvent );

    /**

    * Handles command from the user (or application framework).

    * @param aCommand

    * @return event response, is caller allowed to handle event

    */

    virtual TEventResponse HandleCommandL( const TInt aCommand );

    /**

    * Performs state dependent actions for foreground change event.

    * @param aIsForeground foreground status passed from UI framework

    * @return ETrue if application should behave as in foreground

    */

    virtual TBool HandleForegroundChangedL( const TBool aIsForeground );

    /**

    * Performs state dependent previous actions for foreground change event.

    * @param aIsForeground foreground status passed from UI framework

    * @return ETrue if application should behave as in foreground

    */

    virtual TBool PreHandleForegroundChangedL( const TBool aIsForeground );

    /**

    * Performs state dependent actions for layout change.

    */

    virtual void HandleLayoutChangedL();

    /**

    * Sends DTMF tone if allowed by current state.

    * @param aTone DTMF tone to send

    */

    virtual void StartDtmfTone( const TChar& aTone );

    /**

    * Stops DTMF tone if allowed by current state.

    */

    virtual void StopDtmfTone();

    /**

    * Sets initial application state.

    * @param aCtx state context providing services to states

    * @param aUiStates ui states

    */

    static void SetInitialStateL(

        MVtUiStateContext& aCtx,

        TVtUiStates& aUiStates);

    /**

    * Get whether the shutdown requested

    * @return ETrue if shutdown requested

    */

    static TBool ShutdownRequested();

protected: // for concrete state classes

    /**

    * Destructor, for cleanup.

    */

    virtual ~TVtUiAppStateBase();

    /**

    * Performs entry action for a state.

    */

    virtual void OpenL();

    /**

    * Performs exit action for a state and deletes that state.

    */

    virtual void Close();

    /**

    * Sets current state.

    */

    void ChangeStateL( TVtUiAppStateBase& aNewState );

    /**

    * Sets transition to resetting state as cleanup item.

    */

    void CleanupResetPushL();

    /**

    * Starts shutdown when leave occurred.

    */

    static void TransitionToReset( TAny* aAny );

    /**

    * Ends the call if necessary and starts shutdown.

    * @return ETrue if shutdown started.

    */

    TBool CheckEndActiveCallL();

    /**

    * Returns engine session state.

    * @param aUpdate is state forced to update

    * @return session state

    */

    MVtEngSessionInfo::TSessionState SessionState(

        const TBool aUpdate ) const;

    /**

    * Sets forced lights state in the system.

    */

    void SetLightsState( const TBool aOn );

    /**

    * Delegates engine command execution to the state context.

    */

    template < typename T >

    inline void ExecuteEngineCommand(

        TInt aCommand, T& aParam );

    /**

    * Sets execution state.

    */

    void SetExecState( const TVtUiStates::TVtUiExecState aState );

protected: // constructor

    // c++ constructor

    TVtUiAppStateBase( MVtUiStateContext& aCtx, TVtUiStates& aUiStates );

private: // from MVtUiShutterObserver

    /**

    * Handles 'shutdown ready' event.

    */

    virtual void HandleShutdownReady();

private: // new functions

    /**

    * Updates applications lock state and sends to background if

    * the device is locked.

    */

    void HandleDeviceLockEventL( const TBool aDeviceIsLocked );

protected: // data members

    // Context providing services to states

    MVtUiStateContext&  iCtx;

    // Various application specific state information

    TVtUiStates&        iUiStates;

    /** Prevents sending end call command to call handling if ETrue.

     *  It is not allowed when call clearing is network originated.

     */

    /**

     * shutdown request received

     */

    static TBool iShutdownRequested;

    };

#include "tvtuiappstatebase.inl"

#endif // T_VTUIAPPSTATEBASE_H