/*

* Copyright (c) 2002-2010 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:  EIKON Status Pane control.

*

*/

#ifndef __EIKSPANE_H__

#define __EIKSPANE_H__

#include <eikspmod.h>

#include <coecntrl.h>

#include <coecobs.h>

class CCoeBrushAndPenContext;

class CEikStatusPaneContainer;

class CEikStatusPaneBaseExtension;

class CAknStatuspaneClearer;

class CAknDelayedForegroundObserver;

class CAknStatusPaneDataSubscriber;

class TAknsItemID;

/**

* Status pane flag indicating that a sub-pane exists

* in the status pane.

*/

const TInt KStatusPaneCapsPresentBit         = 1;

/**

* Status pane flag indicating that a sub-pane is owned

* by the application side status pane.

*/

const TInt KStatusPaneCapsAppOwnedBit        = 2;

/**

* Status pane flag indicating that a sub-pane is part of

* a specific status pane layout.

*/

const TInt KStatusPaneCapsInCurrentLayoutBit = 4;

/**

 * The @c MEikStatusPaneObserver interface allows a status pane observer to

 * pick up changes in the size or position of the status pane. Such events

 * will be as a result of layout changes which cause an actual change in the

 * status pane rectangle.

 */

class MEikStatusPaneObserver

	{

public:

	virtual void HandleStatusPaneSizeChange() = 0;

	};

/**

 * The base class for status panes.

 */

class CEikStatusPaneBase : public CBase

	{

public:

    /**

     * Describes the capabilities of a subpane.

     */

    class TPaneCapabilities

        {

    public:

        /**

        * Constructor.

        */

        TPaneCapabilities();

        /**

        * Tests whether the subpane exists in the status pane.

        * 

        * @return @c ETrue if the subpane exists and can be used by the

        *            application, even if the subpane is not visible.

        */

        inline TBool IsPresent() const;

        /**

        * Tests whether the pane is owned by the application or the server.

        * Applications can only interact directly with application owned

        * subpanes.

        *

        * @return @c ETrue if the subpane is owned by the application.

        */

        inline TBool IsAppOwned() const;

        /**

        * Tests if this pane is part of the current status pane layout.

        *

        * @return @c ETrue if pane is part of the current status pane layout.

        */

        inline TBool IsInCurrentLayout() const;

    private:

        inline void SetPresent();

        inline void SetAppOwned();

        inline void SetInCurrentLayout();

    private:

        TInt iFlags;

    private:

        friend class CEikStatusPaneBase;

        };

public:

    /**

    * Destructor.

    */

    IMPORT_C ~CEikStatusPaneBase();

    /**

    * Gets a pointer to the thread's currently active status pane

    * without transferring ownership. 

    *

    * @return Pointer to currently active status pane.

    *         Returns @c NULL if no such pane exists.

    */

    IMPORT_C static CEikStatusPaneBase* Current();

    /**

    * Sets the status pane observer.

    *

    * @param  aObserver  Pointer to status pane observer.

    */

    inline void SetObserver( MEikStatusPaneObserver* aObserver );

    /**

    * Modifies the bounding rectangle so that it lies next to the

    * status pane rectangle.

    *

    * The status pane always places itself along the edge of the screen, so 

    * that it is consistent across applications and the server. It is 

    * assumed that the given bounding rectangle does not extend beyond 

    * the screen area.

    *

    * @param[in,out]  aBoundingRect  The bounding rectangle.

    */

    IMPORT_C void ReduceRect( TRect& aBoundingRect ) const;

    /**

    * Adds and removes pane rectangles from @c aRegion.

    *

    * @param  aRegion              The two-dimensional area from where

    *                              rectangles are removed from or where

    *                              rectangles are added to.

    * @param  aIncludeAppPanes     If @c ETrue, app panes are added, otherwise

    *                              removed.

    * @param  aIncludeServerPanes  If @c ETrue, server panes are added, 

    *                              otherwise removed.

    */

    IMPORT_C void GetShapeL( TRegion& aRegion, 

                             TBool aIncludeAppPanes, 

                             TBool aIncludeServerPanes ) const;

    /**

    * Switches to the specified status pane layout.

    *

    * The actual layout to which this method switches may not be the

    * same as specified in @c aLayoutResourceId parameter.

    * Eg. if landscape mode status pane layout is set with this method,

    * while in portrait mode, it's mapped to the corresponding layout

    * in the portrait mode. This should be noted when using

    * @c CEikStatusPaneBase::CurrentLayoutResId().

    *

    * From release 3.2 on the old status pane layouts are also mapped

    * to the new layouts, ie.

    *  @c R_AVKON_STATUS_PANE_LAYOUT_USUAL ->

    *      @c R_AVKON_STATUS_PANE_LAYOUT_USUAL_EXT

    *

    *  @c R_AVKON_STATUS_PANE_LAYOUT_IDLE  ->

    *      @c R_AVKON_STATUS_PANE_LAYOUT_IDLE_EXT

    *

    * @param aLayoutResourceId Layout resource ID. This must be one of the

    *                          layouts identified in the status pane

    *                          resource structures, otherwise the function

    *                          leaves @c KErrNotFound.

    *                          @see avkon.rsg

    *

    * @leave KErrNotFound      The specified layout does not exist in the

    *                          status pane resource structures.

    */

    IMPORT_C virtual void SwitchLayoutL( TInt aLayoutResourceId );

    /**

    * Sets the visibility of the status pane and it's contents.

    *

    * @param  aVisible  If @c ETrue the status pane and it's contents are set

    *                   visible.

    */

    IMPORT_C virtual void MakeVisible( TBool aVisible );

    /**

    * Sets the status pane and it's contents to dimmed state.

    *

    * @param  aDimmed  If @c ETrue the status pane and it's contents are

    *                  set to dimmed state.

    */

    IMPORT_C virtual void SetDimmed( TBool aDimmed );

    /**

    * Not implemented.

    *

    * @param aFaded Not used.

    */

    IMPORT_C virtual void SetFaded( TBool aFaded );

    /**

    * Handles changes in resources which are shared across the environment.

    * This function responds to the changes in resources by propagating them

    * to sub-parts of the status pane.

    *

    * @param  aType  A message type.

    */

    IMPORT_C virtual void HandleResourceChange( TInt aType );

    /**

    * Returns always @c ETrue. 

    *

    * @return @c ETrue.

    */

    IMPORT_C virtual TBool OkToChangeStatusPaneNow();

    /**

    * Sets all the visual flags at once

    * (@c KEikStatusPaneBaseVisibleBit and

    *  @c KEikStatusPaneBaseDimmedBit).

    * 

    * @param  aFlags  Flags to be set.

    */

    IMPORT_C void SetFlags( TInt aFlags );

    /**

    * Gets status pane settings.

    *

    * @return Flags used by status pane base class.

    */

    IMPORT_C TInt Flags() const;

    /**

    * Gets the visibility of the status pane.

    * 

    * @return @c ETrue if the status pane is visible.

    */

    IMPORT_C TBool IsVisible() const;

    /**

    * Gets the dimmed state of the status pane.

    * 

    * @return @c ETrue if the status pane is dimmed.

    */

    IMPORT_C TBool IsDimmed() const;

    /**

    * Gets the fade status of the status pane.

    * 

    * @return @c ETrue if status pane is faded.

    */

    IMPORT_C TBool IsFaded() const;

    /**

    * Gets the capabilities of a sub-pane in the status pane.

    * 

    * @param   aPaneId  Sub-pane ID.

    *

    * @return Capabilities of the pane.

    */

    IMPORT_C TPaneCapabilities PaneCapabilities( TPaneId aPaneId ) const;

    /**

    * Provides the screen rectangle of a sub-pane.

    * This can be used to set the size of a new control which you want

    * to place in the status pane.

    * 

    * @param   aPaneId  Sub-pane ID.

    *

    * @return The sub-pane rectangle.

    *

    * @leave  KErrNotFound The sub-pane ID is not valid.

    */

    IMPORT_C TRect PaneRectL( TPaneId aPaneId ) const;

    /**

    * Provides the control currently inside a sub-pane.

    * This gives the application direct access to the contents of a pane.

    *

    * @param   aPaneId  Sub-pane ID.

    *

    * @return Pointer to the control instance inside the sub-pane.

    *

    * @leave  KErrNotFound The sub-pane ID is not valid.

    */

    IMPORT_C CCoeControl* ControlL( TPaneId aPaneId ) const;

    /**

    * Swaps the control currently inside a sub-pane.

    * The new control must be a fully constructed control.

    * It will be placed inside the status pane, and the current

    * content will be returned to the caller. 

    * 

    * @param  aPaneId      ID of the sub-pane.

    * @param  aNewControl  A fully constructed control to

    *                      place at @c aPaneId.

    *

    * @return The control  which was at @c aPaneId.

    *

    * @leave  KErrNotFound This can occur before ownership of the new

    *                      control is taken, if the subpane ID is not valid.

    */

    IMPORT_C CCoeControl* SwapControlL( TPaneId aPaneId,

                                        CCoeControl* aNewControl );

    /**

    * Provides access to the container control of a sub-pane.

    * You will need access to the container of a sub pane if you want 

    * to swap in a new control. The container control should be set as the

    * parent window of the new control.

    * It also provides a fast way to get the rectangle of the sub-pane 

    * (@see PaneRect()).

    *

    * @param   aPaneId  ID of the sub-pane.

    *

    * @return Pointer to the new container control for the sub-pane.

    *

    * @leave  KErrNotFound The sub-pane ID is not valid.

    */

    IMPORT_C CCoeControl* ContainerControlL( TPaneId aPaneId ) const;

    /**

    * Provides access to a server-side window group.

    *

    * @return Pointer to the window group.

    */

    inline RWindowGroup* WindowGroup() const;

    /**

    * Draws the control.

    */

    IMPORT_C void DrawNow();

    /**

    * Gets the resource ID of the current layout.

    *

    * @return The resource ID of the current layout.

    *         @see avkon.rsg

    */

    IMPORT_C TInt CurrentLayoutResId() const;

    /**

    * Status pane drawing commands.

    */

    enum TDrawCmd 

        { 

        /** Do not draw. */

        ENoDraw, 

        /** Draw immediately. */

        EDrawNow, 

        /** Draw with low priority. */

        EDrawDeferred 

        };

    /**

    * Sets the skin background ID of sub-panes which

    * are in the CBA area.

    * @internal This method is not exported.

    *

    * @param  aBgID     The skin background ID to be set.

    * @param  aDrawCmd  Whether the status pane is drawn

    *                   when updating the background context,

    *                   (@see @c TDrawCmd).

    */

    void SetCbaAreaBackgroundID( const TAknsItemID& aBgID,

                                 CEikStatusPaneBase::TDrawCmd aDrawCmd );

    /**

    * Returns the current skin background ID of the sub-panes

    * which are in the CBA area.

    * @internal This method is not exported.

    *

    * @return  The skin background ID.

    */

    TAknsItemID CbaAreaBackgroundID();

protected:

    /**

    * C++ default constructor.

    *

    * @param  aEikEnv  An environment for creating controls and utility 

    *                  functions for manipulating them.

    * @param  aParent  Pointer to the parent window group.

    */

    IMPORT_C CEikStatusPaneBase( CEikonEnv& aEikEnv, RWindowGroup* aParent );

    /**

    * Initializes the status pane with standard values. 

    * 

    * @param  aCoreResId  ID of the status pane resource.

    */

    IMPORT_C void BaseConstructL( TInt aCoreResId );

    /**

    * Creates a new model for the status pane.

    *

    * @param  aCoreResId  ID of the status pane resource.

    *

    * @return Pointer to the new status pane model instance.

    */

    virtual CEikStatusPaneModelBase* CreateModelL( TInt aCoreResId ) const = 0;

    /**

    * Creates the sub-panes to the status pane.

    */

    void CreatePanesL();

    /**

    * Creates a sub-pane.

    *

    * @param[in]  aPaneInit  Initial values for the sub-pane.

    */

    void CreatePaneL( const TEikStatusPaneInit& aPaneInit );

    /**

    * Gets a container of a specified sub-pane.

    *

    * @param  aPaneId  The sub-pane ID.

    *

    * @return Pointer to the container of the sub-pane with a given ID.

    */

    CEikStatusPaneContainer* Find( TPaneId aPaneId ) const;

    /**

    * Can be used to determine whether or not the status pane is on

    * application side or server side.

    *

    * @return @c ETrue if the status pane resides in the application side,

    *         @c EFalse if it's on the server side.

    */

    virtual TBool IsApp() const = 0;

    /**

    * Gets the rectangle of the status pane.

    *

    * @return The rectangle used by the status pane.

    */

    inline TRect Rect() const;

    /**

    * Calls @c CCoeControl's @c DrawNow() or @c DrawDeferred() to draw the 

    * status pane. If @c aDraw is @c ENoDraw status pane is not drawed.

    * 

    * @param  aDraw  Status pane drawing command.

    */

    void DoDrawNow( TDrawCmd aDraw );

    /**

    * Gets the status pane clearer.

    *

    * @return Pointer to the status pane clearer instance.

    */

    CAknStatuspaneClearer* Clearer();

    /**

    * Disables the status pane clearer. 

    *

    * @param  aDisabled  Disabled if @c ETrue.

    */

    IMPORT_C void DisableClearer( TBool aDisabled );

    /**

    * Prepares the status pane for the application exit.

    * Clears the status pane.

    */

    IMPORT_C void CommonPrepareForAppExit();

private:

    void DoSwitchLayoutL( TInt aLayoutResourceId, TDrawCmd aDraw );

    void ApplyLayoutL( CEikStatusPaneLayout* aLayout, TDrawCmd aDraw );

    void SetAllInvisible();

    void SetNotNeededInvisible();

public:

    /**

    * Notifies the command button area and status pane observer about the

    * status pane size change. If the status pane is an embedded application,

    * also this application is notified.

    */

    void ReportSizeChange();

private:

    class TSetRectAndVisibility : public MEikStatusPaneLayoutTreeVisitor

        {    

    public:

        TSetRectAndVisibility( TBool aIsApp, CEikStatusPaneBase* aStatusPane );

        void VisitL( CEikStatusPaneLayoutTree* aNode );

    private:

        TBool iIsApp;

        CEikStatusPaneBase* iStatusPane;

        };

	friend class TSetRectAndVisibility;

private:

    void  SetLastUsedResourceId( TInt aResourceId );

    TInt  LastUsedResourceId();

    TInt  ReadInitialUsedResourceIdL( TInt aCoreResId );    

    TInt  InitialUsedResourceId();

    TRect LargestBoundingRect( TRegion& aWholeRegion,

                               TRegion& aRemovedRegion ) const;

    void SetCombinedPaneVisibilityL( TBool aVisible );

protected:

    /**

    * Gets the status pane data subscriber.

    *

    * @return Pointer to the status pane data subscriber.

    */

	CAknStatusPaneDataSubscriber* DataSubscriber() const;

    /**

    * Sets the initial status pane resource ID to an extension class 

    * @c CEikStatusPaneBaseExtension.

    *

    * @param  aResourceId  The initial status pane resource ID.

    */

    void SetInitialUsedResourceId( TInt aResourceId );

    /**

    * Optimizes the status pane region which cleared during

    * status pane layout change.

    *

    * @param         aOldResourceId  Old status pane resource ID.

    * @param         aNewResourceId  New status pane resource ID.

    * @param[in,out] aRegion         Status pane region.

    *                                On return contains only

    *                                the region that needs to be cleared.

    */

	void OptimizeClearerWindowShape( TInt aOldResourceId,

	                                 TInt aNewResourceId,

	                                 TRegion& aRegion );

	/**

	* Sets redraw storing state of the window.

	*

	* @param  aWindow  The window whose redraw storing state is to be set.

	* @param  aOn      @c ETrue to turn redraw storing on.

	*/	

	void SetStoreHandler( RWindow* aWindow, TBool aOn );

protected:

    /**

    * An environment for creating controls and utility functions for 

    * manipulating them.

    */

    CEikonEnv& iEikEnv;

    /**

    * Status pane model class. <br>

    * Own.

    */

    CEikStatusPaneModelBase* iModel;

    /**

    * Flags for the status pane.

    */

    TInt iFlags;

protected:

	typedef CArrayPtrFlat<CEikStatusPaneContainer> CContainerControls;

	CContainerControls* iControls;

private:

	MEikStatusPaneObserver* iObserver;

	RWindowGroup* iParentWindowGroup;

	CEikStatusPaneBaseExtension* iExtension;

	};

/**

 * Application side status pane class.

 *

 * @c CEikStatusPane is the interface through which applications use the

 * status pane. This class synchronises the status pane layout with the

 * server side status pane object. To do this, the @c ApplyCurrentSettingsL()

 * method must be called whenever the owner application switches to the

 * foreground.

 */

NONSHARABLE_CLASS( CEikStatusPane ) : public CEikStatusPaneBase,

                                      public MCoeForegroundObserver

	{

public:

    /**

    * Two-phased constructor.

    *

    * @param  aEikEnv                    An environment for creating controls

    *                                    and utility functions for

    *                                    manipulating them.

    * @param  aParent                    Pointer to the parent window group.

    * @param  aCoreStatusPaneModelResId  Status pane core resource ID.

    * @param  aAppStatusPaneModelResId   Resource ID of the application's

    *                                    status pane.

    *

    * @return Pointer to the created @c CEikStatusPane object.

    */

	IMPORT_C static CEikStatusPane* NewL(

        CEikonEnv& aEikEnv,

        RWindowGroup* aParent,

        TInt aCoreStatusPaneModelResId,

        TInt aAppStatusPaneModelResId = EEikStatusPaneUseDefaults );

    /**

    * Destructor.

    */

	IMPORT_C ~CEikStatusPane();

    /**

    * Synchronises the server status pane layout with the

    * application status pane.

    */

	IMPORT_C void ApplyCurrentSettingsL();

	/**

    * Prepares the status pane for the application exit.

    * Clears the status pane.

    */

	IMPORT_C void PrepareForAppExit();

	/**

    * Sets the visiblility of the status pane and its contents.

    * From @c CEikStatusPaneBase.

    *

    * @param aVisible If @c ETrue the status pane and its

    *                 contents are set visible.

    */

	IMPORT_C virtual void MakeVisible( TBool aVisible );

	/**

    * Sets the status pane and its contents to dimmed state.

    * From @c CEikStatusPaneBase.

    *

    * @param aDimmed If @c ETrue the status pane and its

    *                contents are set to dimmed state.

    */

	IMPORT_C virtual void SetDimmed( TBool aDimmed );

	/**

    * Not implemented.

    * From @c CEikStatusPaneBase.

    *

    * @param aFaded Not used.

    */

	IMPORT_C virtual void SetFaded( TBool aFaded );

	/**

    * Handles changes in resources which are shared across the environment.

    * This function responds to the changes in resources by propagating them

    * to sub-parts of the status pane.

    * From @c CEikStatusPaneBase.

    *

    * @param  aType  A message type.

    */

	IMPORT_C virtual void HandleResourceChange( TInt aType );

	/**

    * Returns always @c ETrue. 

    * From @c CEikStatusPaneBase.

    *

    * @return @c ETrue.

    */

	IMPORT_C virtual TBool OkToChangeStatusPaneNow();

private:

    /**

    * Default C++ constructor.

    *

    * @param  aEikEnv                    An environment for creating controls

    *                                    and utility functions for

    *                                    manipulating them.

    * @param  aParent                    Pointer to the parent window group.

    * @param  aAppStatusPaneModelResId   Resource ID of the application's

    *                                    status pane.

    */

	CEikStatusPane( CEikonEnv& aEikEnv,

	                RWindowGroup* aParent,

	                TInt aAppStatusPaneModelId );

    /**

    * Second-phase constructor.

    *

    * @param  aCoreStatusPaneModelResId  Status pane core resource ID.

    */

	void ConstructL( TInt aCoreStatusPaneModelResId );

    /**

    * Creates the application side status pane model.

    *

    * @param  aCoreResId  Status pane core resource ID.

    */

	virtual CEikStatusPaneModelBase* CreateModelL( TInt aCoreResId ) const;

	/**

    * Can be used to determine whether or not the status pane is on

    * application side or server side.

    *

    * @return @c ETrue

    */

	TBool IsApp() const;

    /**

    * Applies the current status pane flags.

    */

	void ApplyCurrentFlags();

	/**

	* Hides all the sub-panes owned by the application

	* side status pane.

	*/

	void HideAppPanes( TBool aHide );

private: // From base class @c MCoeForegroundObserver.

    /**

    * Handles foreground gain events.

    */

	void HandleGainingForeground();

	/**

    * Handles foreground lose events.

    */

	void HandleLosingForeground();

private:

	/**

    * Reads the initial status pane layout from the status pane resources.

    *

    * @param  aCoreResId                Status pane core resource ID.

    * @param  aAppStatusPaneModelResId  Resource ID specified by the

    *                                   application.

    */

    TInt ReadInitialUsedResourceIdL( TInt aCoreResId,

                                     TInt aAppStatusPaneModelResId );

    /**

    * Handles foreground lose events.

    */

    void DoHandleLosingForegroundL();

private:

	TInt iAppDeclId;

	/** Formerly TEikStatusPaneSyncDrawer* iSyncDrawer */

	TAny* iSpare;

	/** Formerly iServerSpWgId */

	CAknDelayedForegroundObserver* iDelayedForegroundObserver;

	};

/**

* Checks if the pane exists in this status pane.

* Note: this will return @c ETrue if the pane can be used,

* even if it is not visible.

*/

inline TBool CEikStatusPaneBase::TPaneCapabilities::IsPresent() const

    {

    return iFlags & KStatusPaneCapsPresentBit;

    }

/**

* Checks if this pane is owned by application rather than the server.

* Applications can only interact directly with application owned panes.

*/

inline TBool CEikStatusPaneBase::TPaneCapabilities::IsAppOwned() const

    {

    return iFlags & KStatusPaneCapsAppOwnedBit;

    }

/**

* Checks if this pane is part of the current status pane layout.

*/

inline TBool CEikStatusPaneBase::TPaneCapabilities::IsInCurrentLayout() const

    {

    return iFlags & KStatusPaneCapsInCurrentLayoutBit;

    }

/**

* Set the status pane observer.

*/

inline void CEikStatusPaneBase::SetObserver( MEikStatusPaneObserver* aObserver )

    {

    iObserver = aObserver;

    }

/**

* Gets the status pane rectangle.

*/

inline TRect CEikStatusPaneBase::Rect() const

    {

    return iModel->CurrentLayout()->Rect();

    }

/**

* Gets the window group that this status pane belongs to.

*/

inline RWindowGroup* CEikStatusPaneBase::WindowGroup() const

    {

    return iParentWindowGroup;

    }

#endif // __EIKSPANE_H__