/*

* Copyright (c) 2002-2007 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 button group container class definition.

*

*/

#ifndef __EIKBTGPC_H__

#define __EIKBTGPC_H__

#include <coecntrl.h>

#include <eikbtgrp.h>

#include <eikcmobs.h>

#include <lafpublc.h>

#include <uikon.hrh>

#include <AknControl.h>

class MEikCommandObserver;

class CEikButtonGroupStack;

class CEikCommandButton;

class CEikListBox;

/**

 * The CEikButtonGroupContainer class provides a wrapper around the different button arrays

 * used in pen and no-pen devices. 

 *

 * @lib eikcoctl.lib 

 * @since S60 0.9 

 */

NONSHARABLE_CLASS(CEikButtonGroupContainer) : public CAknControl, public MEikCommandObserver

    {

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(0x101F4107)

    /**

     * Describes how the container is being used.

     *

     * The enumeration is used by the system to create the appropriate (UI variant-specific)

     * button group for the specified type.

     */

    enum TUse

        {

        EView          = SLafButtonGroupContainer::EView,         ///< In a view.

        EDialog        = SLafButtonGroupContainer::EDialog,       ///< In a dialog.

        EToolbar       = SLafButtonGroupContainer::EToolbar,      ///< In a toolbar.

        ECba           = SLafButtonGroupContainer::ECba,          ///< In a control button array.

        EDialogButtons = SLafButtonGroupContainer::EDialogButtons ///< In dialog buttons.

        };

    /**

     * Describes the orientation of the container.

     */        

    enum TOrientation

        {

        EVertical   = SLafButtonGroupContainer::EVertical,  ///< Buttons are laid out vertically.

        EHorizontal = SLafButtonGroupContainer::EHorizontal ///< Buttons are laid out horizontally.

        };

    /**

     * Relative positions of the container and the control which uses it.

     */        

    enum TLocation

        {

        /** The button group is internal to the control which is using it. E.g. dialog buttons. */

        EInternal   = SLafButtonGroupContainer::EInternal, 

        /** The button group is external to the control which is using it. E.g. toolbar or cba. */

        EExternal   = SLafButtonGroupContainer::EExternal  

        };

    /**

     * Flags for the display of hotkeys.

     */        

    enum THotKeyFlags

        {

        EShowHotKey      = 0x01, ///< Hotkeys for commands should be shown.

        EPlainHotKey     = 0x02  ///< Hotkeys for commands should not be shown.

        };

    /** 

     * Additional flags.

     */         

    enum TFlags

        {

        EAddToStack      = 0x01, ///< Not used.

        EDelayActivation = 0x02, ///< If set, the container is not activated during construction.

        EUseMaxSize      = 0x04,  ///< Not used.

        EIsEmbedded      = 0x08, ///< Embedded in a dialog or popup.

        };

    /**

     * Defines the positions for each command.   

     */   

    enum TCommandPosition

        {

        ELeftSoftkeyPosition    = 0, ///< Position for left softkey.

        ERightSoftkeyPosition   = 2, ///< Position for right softkey.

        EMiddleSoftkeyPosition  = 3  ///< Position for middle softkey.

        };

public:

    /**

     * Creates a button group container in its own window.

     *

     * @param aUse The button group's type. 

     * @param aOrientation The button group's orientation. You need specify this 

     *                     only for devices that can layout their buttons either 

     *                     horizontally or vertically.

     * @param aCommandObserver A command observer to be notified of commands on 

     *                         the container.

     * @param aResourceId A resource containing descriptions of buttons in the group. 

     *                    This can be NULL if buttons are to be added dynamically.

     * @param aFlags The button group's flags.

     * @return Button group container object.

     */ 

    IMPORT_C static CEikButtonGroupContainer* NewL(

        TUse aUse,

        TOrientation aOrientation,

        MEikCommandObserver* aCommandObserver,

        TInt aResourceId,

        TUint aFlags = EAddToStack);

    /**

     * Creates a button group container in its parent control's window.

     *

     * @param aUse The button group's type.

     * @param aOrientation The button group's orientation. You need specify this 

     *                     only for devices that can layout their buttons either 

     *                     horizontally or vertically.

     * @param aCommandObserver A command observer to be notified of commands on 

     *                         the container.

     * @param aResourceId A resource containing descriptions of buttons in the group. 

     *                    This can be NULL if buttons are to be added dynamically.

     * @param aParent The control's parent.

     * @param aFlags The button group's flags.

     * @return Button group container object.

     */         

    IMPORT_C static CEikButtonGroupContainer* NewL(

        TUse aUse,

        TOrientation aOrientation,

        MEikCommandObserver* aCommandObserver,

        TInt aResourceId,

        const CCoeControl& aParent,

        TUint aFlags = EAddToStack);

    /**

     * Creates a button group container in given window group.

     *

     * @param aUse The button group's type.

     * @param aOrientation The button group's orientation. You need specify this 

     *                     only for devices that can layout their buttons either 

     *                     horizontally or vertically.

     * @param aCommandObserver A command observer to be notified of commands on 

     *                         the container.

     * @param aResourceId A resource containing descriptions of buttons in the group. 

     *                    This can be NULL if buttons are to be added dynamically.

     * @param aParentWg The parent window group.

     * @param aFlags The button group's flags.

     * @return Button group container object.

     */        

    IMPORT_C static CEikButtonGroupContainer* NewL(

        TUse aUse,

        TOrientation aOrientation,

        MEikCommandObserver* aCommandObserver,

        TInt aResourceId,

        RWindowGroup& aParentWg,

        TUint aFlags = EAddToStack);

    /**

     * Destructor.

     */        

    IMPORT_C ~CEikButtonGroupContainer();

    /**

     * Gets a pointer to an application's currently active CEikButtonGroupContainer (if any).

     *

     * Returns NULL if there are no containers active or none suitable for sharing. 

     * Ownership of the returned pointer is not transferred.

     *

     * @return Pointer to the button group container.

     */    

    IMPORT_C static CEikButtonGroupContainer* Current();

public:

    /**

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

     *

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

     *                  If the position is out of range this function raises a panic.

     * @param aCommandId Command ID the button will send.

     * @param aText Text for the button.

     */

    inline void SetCommandL(

        TInt aPosition, 

        TInt aCommandId, 

        const TDesC& aText);

    /**

     * Sets a command button's bitmap and command ID.

     *

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

     *                  If the position is out of range this function raises a panic.

     * @param aCommandId Command ID the button will send.

     * @param aBitmap The bitmap for the button.

     * @param aMask The mask bitmap for aBitmap.

     */    

    inline void SetCommandL(

        TInt aPosition, 

        TInt aCommandId, 

        const CFbsBitmap& aBitmap,

        const CFbsBitmap& aMask);

    /**

     * Sets a command button's bitmap, text and command ID.

     *

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

     *                  If the position is out of range, the function raises a panic.

     * @param aCommandId Command ID the button will send.

     * @param aText The text for the button.

     * @param aBitmap The bitmap for the button.

     * @param aMask The mask bitmap for aBitmap.

     */        

    inline void SetCommandL(

        TInt aPosition, 

        TInt aCommandId, 

        const TDesC& aText,

        const CFbsBitmap& aBitmap,

        const CFbsBitmap& aMask);

    /**

     * Sets a command button's bitmap and command ID. The bitmap and its mask are read

     * from a file.

     *

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

     *                  If the position is out of range, the function raises a panic.

     * @param aCommandId Command ID the button will send.

     * @param aFile A multi-bitmap file, containing mask and bitmap images.

     * @param aBitmapId ID of the bitmap within aFile.

     * @param aMaskId ID of the mask within aFile.

     */        

    inline void SetCommandL(

        TInt aPosition, 

        TInt aCommandId, 

        const TDesC& aFile,

        TInt aBitmapId,

        TInt aMaskId);

    /**

     * Sets a command button's bitmap, text label and command ID. The bitmap and its 

     * mask are read from a file.

     *

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

     *                  If the position is out of range, the function raises a panic.

     * @param aCommandId Command ID the button will send.

     * @param aText The text for the button.

     * @param aFile A multi-bitmap file, containing mask and bitmap images.

     * @param aBitmapId ID of the bitmap within aFile.

     * @param aMaskId ID of the mask within aFile.

     */        

    inline void SetCommandL(

        TInt aPosition, 

        TInt aCommandId, 

        const TDesC& aText,

        const TDesC& aFile,

        TInt aBitmapId,

        TInt aMaskId);

    /**

     * Sets a command button's bitmap, text label and command ID. The bitmap, mask,

     * text and command ID are all read from resource.

     *

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

     *                  If the position is out of range, the function raises a panic.

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

     */        

    inline void SetCommandL(

        TInt aPosition, 

        TInt aResourceId);

    /**

     * Sets a command button's text. The button to change is identified by its command ID.

     *

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

     * @param aText The text for the button.

     * @leave KErrNotFound The ID cannot be matched to any button.

     */        

    inline void SetCommandL(

        TInt aCommandId, 

        const TDesC& aText);

    /**

     * Sets a command button's bitmap and mask. The button to change is identified 

     * by its command ID.

     *

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

     * @param aBitmap Bitmap for the button.

     * @param aMask Mask bitmap for aBitmap.

     * @leave KErrNotFound The ID cannot be matched to any button.

     */        

    inline void SetCommandL(

        TInt aCommandId, 

        const CFbsBitmap& aBitmap,

        const CFbsBitmap& aMask);

    /**

     * Sets a command button's bitmap, mask and text. The button to change is 

     * identified by its command ID.

     *

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

     * @param aText Text for the button.

     * @param aBitmap Bitmap for the button.

     * @param aMask Mask bitmap for aBitmap.

     */        

    inline void SetCommandL(

        TInt aCommandId, 

        const TDesC& aText,

        const CFbsBitmap& aBitmap,

        const CFbsBitmap& aMask);

    /**

     * Sets a command button's bitmap and mask. The bitmap and mask are read from 

     * a multi bitmap file. The button to change is identified by its command ID.

     *

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

     * @param aFile A multi-bitmap file, containing mask and bitmap images.

     * @param aBitmapId ID of the bitmap within aFile.

     * @param aMaskId ID of the mask within aFile.

     */        

    inline void SetCommandL(

        TInt aCommandId, 

        const TDesC& aFile,

        TInt aBitmapId,

        TInt aMaskId);

    /**

     * Sets a command button's bitmap, mask and text. The bitmap and its mask are read 

     * from a multi bitmap file. The button to change is identified by its command ID.

     *

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

     * @param aText Text for the button.

     * @param aFile  A multi-bitmap file, containing mask and bitmap images.

     * @param aBitmapId ID of the bitmap within aFile.

     * @param aMaskId ID of the mask within aFile.

     */        

    inline void SetCommandL(

        TInt aCommandId, 

        const TDesC& aText,

        const TDesC& aFile,

        TInt aBitmapId,

        TInt aMaskId);

    /**

     * Initialises the group of command buttons from a resource.

     *

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

     */        

    IMPORT_C void SetCommandSetL(

        TInt aResourceId);   

    /**

     * Adds a command button with a text label and command ID.

     *

     * @param aPosition The position in the button group for the new button.

     * @param aCommandId Command ID for the new button.

     * @param aText Text for the button.          

     */   

    inline void AddCommandL(

        TInt aPosition, 

        TInt aCommandId,

        const TDesC& aText);

    /**

     * Adds a command button with a bitmap label and command ID.

     *

     * @param aPosition The position in the button group for the new button.

     * @param aCommandId Command ID for the new button.

     * @param aBitmap Bitmap for the button.

     * @param aMask Mask bitmap for aBitmap.

     */        

    inline void AddCommandL(

        TInt aPosition, 

        TInt aCommandId,

        const CFbsBitmap& aBitmap,

        const CFbsBitmap& aMask);

    /**

     * Adds a command button with a command ID and a label containing both 

     * a bitmap and text.

     *

     * @param aPosition The position in the button group for the new button.

     * @param aCommandId Command ID for the new button.

     * @param aText Text for the button.

     * @param aBitmap Bitmap for the button.

     * @param aMask Mask bitmap for aBitmap.

     */        

    inline void AddCommandL(

        TInt aPosition, 

        TInt aCommandId,

        const TDesC& aText,

        const CFbsBitmap& aBitmap,

        const CFbsBitmap& aMask);

    /**

     * Adds a command button with a command ID and a bitmap which is read from a file.

     *

     * @param aPosition The position in the button group for the new button.

     * @param aCommandId Command ID for the new button.

     * @param aFile Multi-bitmap file containing the bitmap and mask.

     * @param aBitmapId ID of the bitmap within aFile.

     * @param aMaskId ID of the mask within aFile.

     */        

    inline void AddCommandL(

        TInt aPosition, 

        TInt aCommandId,

        const TDesC& aFile,

        TInt aBitmapId,

        TInt aMaskId);

    /**

     * Adds a command button with a command ID and a label containing both a bitmap 

     * and text. The bitmap and mask are read from file.

     *

     * @param aPosition The position in the button group for the new button.

     * @param aCommandId Command ID for the new button.

     * @param aText Text for the button.

     * @param aFile Multi-bitmap file containing the bitmap and mask.

     * @param aBitmapId ID of the bitmap within aFile.

     * @param aMaskId ID of the mask within aFile.

     */        

    inline void AddCommandL(

        TInt aPosition, 

        TInt aCommandId,

        const TDesC& aText,

        const TDesC& aFile,

        TInt aBitmapId,

        TInt aMaskId);

    /**

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

     * button stack. This function behaves similarly to SetCommandL() but allows 

     * the previous command button to be retrieved by calling RemoveCommandFromStack().

     *

     * @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.

     */        

    inline void AddCommandToStackL(

        TInt aPosition,

        TInt aCommandId,

        const TDesC& aText);

    /**

     * Pushes a command button with a bitmap, mask and command ID onto a position's 

     * button stack. This function behaves similarly to SetCommandL() but allows the 

     * previous command button to be retrieved by calling RemoveCommandFromStack(). 

     *

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

     * @param aCommandId Command ID the button will send.

     * @param aBitmap Bitmap for the button.

     * @param aMask Mask bitmap for aBitmap.

     */        

    inline void AddCommandToStackL(

        TInt aPosition,

        TInt aCommandId,

        const CFbsBitmap& aBitmap,

        const CFbsBitmap& aMask);

    /**

     * Pushes a command button with text, bitmap, mask and a command ID onto a position's

     * button stack. This function behaves similarly to SetCommandL() but allows the 

     * previous command button to be retrieved by calling RemoveCommandFromStack().

     *

     * @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 Bitmap for the button.

     * @param aMask Mask bitmap for aBitmap.

     */        

    inline void AddCommandToStackL(

        TInt aPosition,

        TInt aCommandId,

        const TDesC& aText,

        const CFbsBitmap& aBitmap,

        const CFbsBitmap& aMask);

    /**

     * Pushes a command button with a bitmap, mask and command ID onto a position's button 

     * stack. The bitmap and mask are read from a file. This function behaves similarly to 

     * SetCommandL() but allows the previous command button to be retrieved by calling 

     * RemoveCommandFromStack().

     *

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

     * @param aCommandId Command ID the button will send.

     * @param aFile A multi-bitmap file containing mask and bitmap.

     * @param aBitmapId Index into the file of the bitmap.

     * @param aMaskId Index into the file of the bitmap mask.

     */        

    inline void AddCommandToStackL(

        TInt aPosition,

        TInt aCommandId,

        const TDesC& aFile,

        TInt aBitmapId,

        TInt aMaskId);

    /**

     * Pushes a command button with text, bitmap, mask and command button onto a position's 

     * button stack. The bitmap and mask are read from a file. This function behaves similarly

     * to SetCommandL() but allows the previous command button to be retrieved by calling 

     * RemoveCommandFromStack(). 

     *