/*

 * 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__