/*

* Copyright (c) 2002-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:  EIKON control button array and cba button class definitions.

*

*/

#ifndef __EIKCBA_H__

#define __EIKCBA_H__

#include <eikctgrp.h>

#include <badesca.h>

#include <eikbtgrp.h>

#include <eiksbobs.h>

#include <eiksbfrm.h>

#include <eikimage.h>

#include <AknControl.h>

#include <AknsItemData.h> // TAknsItemID

#include <babitflags.h>   // TBitFlags

class CEikLabel;

class CEikCbaButton;

class CCoeBrushAndPenContext;

class MEikCommandObserver;

class TCoeColorUse;

class CAknScrollBar;

class TEikScrollBarModel;

class CEikEnhancedCbaButton;

class CEikCommandTable;

class CAknsBasicBackgroundControlContext;

class CAknsLayeredBackgroundControlContext;

class CAknsMaskedLayerBackgroundControlContext;

class CEikCbaExtension;

const TInt KMaxCbaLabelLength = 32;

const TInt KMaxButtonsInCommandTable = 4;

/**

 * Defines a Control Button Array control, used in Avkon to define the softkeys in the

 * control pane.

 *

 * @lib eikcoctl.lib

 * @since S60 0.9  

 */

NONSHARABLE_CLASS(CEikCba) :

    public CEikControlGroup, 

    public MEikEnhancedButtonGroup, 

    public MEikScrollBarObserver,

    public MCoeControlObserver

    {

public: 

    /** 

     * Declares an object type for a class, in order to allow the object

     * provider mechanism to locate and provide objects from the class.

     */

    DECLARE_TYPE_ID(0x101F4105)

    /**

     * Creates a new control button array.

     *

     * @internal

     * @param aPrevious Previous Cba, used in MinimumSize().

     * @param aCommandObserver Command observer for softkey events.

     * @param aParentWg The parent window group.

     * @return Control button array object.

     */

    static CEikCba* NewL(

        const CEikCba* aPrevious, 

        MEikCommandObserver* aCommandObserver, 

        RWindowGroup* aParentWg);

    /**

     * Creates a new control button array.

     *

     * @internal

     * @param aResourceId A resource describing the Cba.

     * @param aPrevious Previous Cba, used in MinimumSize().

     * @param aCommandObserver Command observer for softkey events.

     * @param aParentWg The parent window group.

     * @return Control button array object.

     */        

    static CEikCba* NewL(

        TInt aResourceId,

        const CEikCba* aPrevious,

        MEikCommandObserver* aCommandObserver,

        RWindowGroup* aParentWg);

    /**

     * Creates a new control button array.

     *

     * @internal

     * @param aPrevious Previous Cba, used in MinimumSize().

     * @param aCommandObserver Command observer for softkey events.

     * @param aParentWg The parent window group.

     * @return Control button array object.

     */        

    static CEikCba* NewLC(

        const CEikCba* aPrevious,

        MEikCommandObserver* aCommandObserver,

        RWindowGroup* aParentWg);

    /**

     * Creates a new control button array

     *

     * @since S60 5.2

     * @internal

     * @param aPrevious Previous Cba, used in MinimumSize()

     * @param aCommandObserver Command observer for softkey events

     * @param aParentWg The parent window group

     * @param aFlags CEikButtonGroupContainer::EIsEmbedded if CBA is embedded

     *               inside another control (popup/dialog/setting page)

     * @return Control button array object

     */        

    static CEikCba* NewLC(

        const CEikCba* aPrevious,

        MEikCommandObserver* aCommandObserver,

        RWindowGroup* aParentWg, TUint aFlags );

    /**

     * Creates a new control button array.

     *

     * @internal

     * @param aResourceId A resource describing the Cba.

     * @param aPrevious Previous Cba, used in MinimumSize().

     * @param aCommandObserver Command observer for softkey events.

     * @param aParentWg The parent window group.

     * @return Control button array object.

     */         

    static CEikCba* NewLC(

        TInt aResourceId,

        const CEikCba* aPrevious,

        MEikCommandObserver* aCommandObserver,

        RWindowGroup* aParentWg);

    /**

     * Creates a new control button array

     *

     * @since S60 5.2

     * @internal

     * @param aResourceId A resource describing the Cba

     * @param aPrevious Previous Cba, used in MinimumSize()

     * @param aCommandObserver Command observer for softkey events

     * @param aParentWg The parent window group

     * @param aFlags CEikButtonGroupContainer::EIsEmbedded if CBA is embedded

     *               inside another control (popup/dialog/setting page)

     * @return Control button array object

     */         

    static CEikCba* NewLC(

        TInt aResourceId,

        const CEikCba* aPrevious,

        MEikCommandObserver* aCommandObserver,

        RWindowGroup* aParentWg, TUint aFlags );

    /**

     * Destructor.

     */        

    ~CEikCba();

public: // new methods

    /**

     * Gets the maximum number of buttons that can be supported by the device.

     *

     * @internal

     * @return The number of command buttons supported.

     */

    TInt MaxCommands() const;

    /**

     * Updates the cba labels.

     *

     * @internal

     * @param aScrollerOn If this is set, the short labels are used instead 

     *                    of the long ones. To be used if there is an (old style) 

     *                    scroller between the softkeys.     

     */    

    void UpdateCbaLabels(TBool aScrollerOn);

    /**

     * For checking whether the middle softkey is supported in the platform.

     * 

     * @internal

     * @return ETrue if the middle softkey is supported in the plaftorm.

     */

    TInt MSKEnabledInPlatform() const;

    /** 

     * Sets the scroll bar frame observer.

     * 

     * @internal

     * @param aObserver The scroll bar frame observer.

     */ 

    void SetSBFrameObserver(MEikScrollBarObserver* aObserver);

    /** 

     * Sets the scroll bar model.

     *

     * @internal

     * @param aModel The scroll bar model.

     */ 

    void SetScrollBarModelL(TEikScrollBarModel* aModel);

    /** 

     * Returns the scroll bar frame.

     *

     * @internal

     * @return The scroll bar frame.

     */ 

    const CEikCbaScrollBarFrame* ScrollBarFrame() const;

    /** 

     * Returns the vertical scroll bar as a control.

     *

     * @internal The vertical scroll bar as a control

     */

    CAknScrollBar* VScrollBarAsControl();

    /** 

     * Replaces empty scroll bar with actual arrow head scroll bar.

     *

     * @internal

     * @since S60 3.0

     */    

    void CreateArrowHeadScrollBarL(); 

     /** 

     * For external set the MSK icon

     * Returns ETrue if option is ok, EFalse is not.

     * @param aId icon bitmap IID

     * @param aBmpFile file path.

     * @param aBmp Bitmap ID.

     * @param aBmpM Bitmap mask ID.

     * @param aEnable ETrue for set icon, EFalse for use default icon.

     */

    IMPORT_C TBool UpdateMSKIconL( 

        const TAknsItemID& aId,

        const TDesC& aBmpFile,

        const TInt32 aBmp,

        const TInt32 aBmpM,

        TBool aEnable);

    /**

     * Enables or disables item specific softkey. If enabled then SK1's 

     * visibility is determined by the screen content. If there's a list or 

     * grid with visible highlight (i.e. highlight is brought visible via 

     * hardware keys) on the display or SK1's associated command is 

     * @c EAknSoftkeyOptions then SK1 is visible, otherwise it's hidden. This

     * method has no effect if the the application isn't single click enabled. 

     * Item specific softkey is enabled by default.

     *

     * @since S60 5.2

     *

     * @param aEnable ETrue to enable item specific softkey, EFalse to disable.

     */

     IMPORT_C void EnableItemSpecificSoftkey( TBool aEnable );

public:

    /**

     * From CEikControlGroup.

     * Adds a wrapped control to the control group array at the given index position.

     * Overridden to prevent setting container window.

     * 

     * @param aGroupControl The control to add to the group.

     * @param aIndex The index for the added control.

     */

    void InsertControlL(TEikGroupControl& aGroupControl, TInt aIndex);

    /**

     * From MEikButtonGroup.

     * Sets a command button's text and command ID. Note that this implementation does 

     * not support bitmap and mask.

     *

     * @param aPosition The position within the button group of the button to change. 

     * @param aCommandId Command ID the button will send.

     * @param aText The text for the button.     

     * @param aBitmap Not used.

     * @param aMask Not used.

     */     

    void SetCommandL(

        TInt aPosition,

        TInt aCommandId,

        const TDesC* aText,

        const CFbsBitmap* aBitmap,

        const CFbsBitmap* aMask);

    /**

     * From MEikButtonGroup.

     * Sets a command button's text label and command ID. The text and command ID are all 

     * read from resource. Note that this implementation does not support bitmap and mask.

     *

     * @internal     

     *

     * @param aPosition The position within the button group of the button to change.

     * @param aResourceId Resource ID specifying the text and command ID.

     *

     */        

    void SetCommandL(TInt aPosition, TInt aResourceId);

    /**

     * From MEikButtonGroup.

     * Initialises the group of command buttons from a resource.

     * Note that this implementation does not support bitmap and mask.

     *

     * @internal     

     *

     * @param aResourceId ID of the resource structure specifying the command buttons.     

     */    

    void SetCommandSetL(TInt aResourceId);

    /**

     * From MEikButtonGroup.

     * Not supported.

     *

     * @internal     

     *

     * @param aPosition Not used.

     * @param aCommandId Not used.

     * @param aText Not used.

     * @param aBitmap Not used.

     * @param aMask Not used.

     * @leave KErrNotSupported If called.

     */    

    void AddCommandL(

        TInt aPosition,

        TInt aCommandId,

        const TDesC* aText,

        const CFbsBitmap* aBitmap,

        const CFbsBitmap* aMask);

    /**

     * From MEikButtonGroup.

     * Pushes a command button with text and a command ID onto a position's button stack.

     * Note that this implementation does not support bitmap and mask.

     *

     * @internal     

     *

     * @param aPosition The position in the button group at which to add the command button.

     * @param aCommandId Command ID the button will send.

     * @param aText Text for the button.

     * @param aBitmap Not used.

     * @param aMask Not used.

     */        

    void AddCommandToStackL(

        TInt aPosition,

        TInt aCommandId,

        const TDesC* aText,

        const CFbsBitmap* aBitmap,

        const CFbsBitmap* aMask);

    /**

     * From MEikButtonGroup.

     * Pushes a command button onto a position's button stack. The text and command ID are all 

     * read from resource. Note that this implementation does not support bitmap and mask.

     *

     * @internal     

     *

     * @param aPosition The position in the button group at which to push the command button.

     * @param aResourceId ID of a resource specifying the text and command ID.

     */        

    void AddCommandToStackL(TInt aPosition, TInt aResourceId);

    /**

     * From MEikButtonGroup.

     * As with SetCommandL() but for a set of buttons, also allows the previous command button 

     * to be retrieved by calling RemoveCommand(). Note that this implementation does not 

     * support bitmap and mask.

     *

     * @internal     

     *

     * @param aResourceId Resource describing the set of command buttons.

     */    

    void AddCommandSetToStackL(TInt aResourceId);

    /**

     * From MEikButtonGroup.

     * Not supported.

     *

     * @internal     

     * 

     * @param aCommandId Not used.

     */    

    void SetDefaultCommand(TInt aCommandId);

    /**

     * From MEikButtonGroup.

     * Calculates minimum size required to display the buttons defined in the 

     * specified resource structure.

     *

     * @internal     

     *

     * @param aResourceId The ID of the resource structure describing the button group.

     * @return Minimum size required to display the button group defined in the specified 

     *         resource structure.     

     */    

    TSize CalcMinimumSizeL(TInt aResourceId);

    /**

     * From MEikButtonGroup.

     * Removes the command identified by aCommandId, in position aPosition in the 

     * group, from the command stack. Automatically retrieves the previous command 

     * details. Commands are added to the stack by calling AddCommandToStackL.

     *

     * @internal     

     *

     * @param aPosition The position in the button group from which to remove the 

     *                  command button.

     * @param aCommandId Command ID.     

     */    

    void RemoveCommandFromStack(TInt aPosition, TInt aCommandId);

    /**

     * From MEikButtonGroup.

     * Returns the command position by command id.

     *

     * @internal     

     *

     * @param aCommandId The button's command id.

     * @return The command position in the button group.     

     */    

    TInt CommandPos(TInt aCommandId) const;

    /**

     * From MEikButtonGroup.

     * Dims or undims a button without drawing it. 

     *

     * @internal     

     *

     * @param aCommandId Command ID of the button to change.

     * @param aDimmed ETrue to dim the specified command. EFalse to undim the specified command.

     */

    void DimCommand(TInt aCommandId, TBool aDimmed);

    /**

     * From MEikButtonGroup.

     * Determines whether the button with the specified command ID is dimmed. 

     *

     * @internal     

     *

     * @param aCommandId The command ID.

     * @return ETrue if the specified command is dimmed. EFalse if the specified command is 

     *               not dimmed.

     */    

    TBool IsCommandDimmed(TInt aCommandId) const;

    /**

     * From MEikButtonGroup.

     * Makes the button with the specified id either visible, or invisible. 

     *

     * @internal     

     *

     * @param aCommandId Specifies the button to alter.

     * @param aVisible ETrue to make the specified button visible. EFalse to make the specified

     *                 button invisible.     

     */    

    void MakeCommandVisible(TInt aCommandId, TBool aVisible);

    /**

     * From MEikButtonGroup.

     * Tests whether the button with the specified command ID is visible.

     *

     * @internal     

     *

     * @param aCommandId Specifies the button.

     * @return ETrue if the specified button is visible. EFalse if the specified button is 

     *               not visible.

     */    

    TBool IsCommandVisible(TInt aCommandId) const;

    /**

     * From MEikButtonGroup.

     * Not supported.

     *

     * @internal     

     *

     * @param aCommandId Not used.

     */    

    void AnimateCommand(TInt aCommandId);

    /**

     * From MEikButtonGroup.

     * Returns the button group as a control.

     *

     * @internal     

     *

     * @return The button group as a control.

     */    

    CCoeControl* AsControl();

    /**

     * From MEikButtonGroup.

     * Returns the button group as a control.

     *

     * @internal     

     *

     * @return The button group as a control.

     */    

    const CCoeControl* AsControl() const;

    /**

     * From MEikButtonGroup.

     * Sets the boundary rectangle for externally-positioned button groups. 

     * For use by EExternal button groups only.

     *

     * @internal     

     *

     * @param aBoundingRect Not used.

     */    

    void SetBoundingRect(const TRect& aBoundingRect);

    /**

     * From MEikButtonGroup.

     * Subtracts the area occupied by the button group from the specified bounding rectangle.

     * This method should be used in preference to querying the container's area at all times.