/*

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