/*

* Copyright (c) 2005-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:  Button component.

*

*/

#ifndef __AKNBUTTON_H__

#define __AKNBUTTON_H__

//  INCLUDES

#include <AknControl.h>

#include <AknIconUtils.h>

#include <AknUtils.h>

// FORWARD DECLARATIONS

class CGulIcon;

class CAknButton;

class CAknButtonExtension; 

class CAknInfoPopupNoteController;

class CAknButtonStateExtension;

class CAknPictographInterface;

class CAknsFrameBackgroundControlContext;

class CAknResourceProvider;

// CLASS DECLARATION

/**

*  Class which represents one of the button states. 

*

*  @lib eikcoctl.lib

*  @since Series 60 3.1

*/

class CAknButtonState : public CBase

    {           

    public: // Constructors and destructors

        /**

         * Destructor.

         */

        IMPORT_C ~CAknButtonState();

    protected: // Constructors and destructors

        /**

         * Constructor.

         *

         * @param aFlags The flags for the button state

         */

        IMPORT_C CAknButtonState( const TInt aFlags );

        /**

         * Symbian 2nd phase constructor.

         *

         * @param aIcon The icon for the normal state. Takes ownership.

         * @param aDimmedIcon The icon for the dimmed state. Takes ownership.

         * @param aPressedIcon The icon for the pressed down. Takes ownership.

         * @param aHoverIcon The icon for the hover state. Takes ownership.

         * @param aText The text inside the button.

         * @param aHelpText The text for the tooltip.

         */

        IMPORT_C void ConstructL( CGulIcon* aIcon,

                                  CGulIcon* aDimmedIcon, 

                                  CGulIcon* aPressedIcon,

                                  CGulIcon* aHoverIcon,

                                  const TDesC& aText, 

                                  const TDesC& aHelpText );

        /**

         * Symbian 2nd phase constructor.

         *

         * @param aFilePath The path to the file which contains icons.

         * @param aBmpId The bitmap ID for the normal state icon.

         * @param aMaskId The mask ID for the normal state icon.

         * @param aDimmedBmpId The bitmap ID for the dimmed state icon.

         * @param aDimmedMaskId The mask ID for the dimmed state icon.

         * @param aPressedBmpId The bitmap ID for the pressed down state.

         * @param aPressedMaskId The mask ID for the pressed down state.

         * @param aHoverBmpId The bitmap ID for the hover state icon.

         * @param aHoverMaskId The mask ID for the hover state icon.

         * @param aText The text inside the button.

         * @param aHelpText The text for the tooltip.

         * @param aId Item ID of the masked bitmap to be created for skin 

         *          specific icon.

         * @param aDimmedId Item ID of the dimmed masked bitmap to be created

         *          for skin specific icon.

         * @param aPressedId Item ID of the pressed masked bitmap to be created

         *          for skin specific icon.

         * @param aHoverId Item ID of the masked hover bitmap to be created

         *          for skin specific icon.

         */

        IMPORT_C void ConstructL( const TDesC& aFilePath, 

                                  const TInt aBmpId, 

                                  const TInt aMaskId,

                                  const TInt aDimmedBmpId, 

                                  const TInt aDimmedMaskId,

                                  const TInt aPressedBmpId, 

                                  const TInt aPressedMaskId,

                                  const TInt aHoverBmpId,

                                  const TInt aHoverMaskId,

                                  const TDesC& aText, 

                                  const TDesC& aHelpText,

                                  const TAknsItemID& aId = KAknsIIDNone, 

                                  const TAknsItemID& aDimmedId = KAknsIIDNone, 

                                  const TAknsItemID& aPressedId = KAknsIIDNone,

                                  const TAknsItemID& aHoverId = KAknsIIDNone );

    public: // New functions

        /**

         * Provides the icon for the normal state.

         *

         * @return The icon for the normal state.

         */

        IMPORT_C const CGulIcon* Icon() const;

        /**

         * Provides the icon for the dimmed state.

         *

         * @return The icon for the dimmed state.

         */

        IMPORT_C const CGulIcon* DimmedIcon() const;

        /**

         * Provides the icon for the pressed down (not released) state.

         *

         * @return The icon for the pressed down (not released) state.

         */

        IMPORT_C const CGulIcon* PressedIcon() const;

        /**

         * Provides the icon for the hover state.

         *

         * @return The icon for the hover state.

         */

        IMPORT_C const CGulIcon* HoverIcon() const;

        /**

         * Provides the text inside the button.

         *

         * @return The button text.

         */

        IMPORT_C const TDesC& Text() const;

        /**

         * Provides the text inside the help note.

         *

         * @return The tooltip text.

         */

        IMPORT_C const TDesC& HelpText() const;

        /**

         * Provides the flags for the state.

         *

         * @return The state flags.

         */

        IMPORT_C TInt Flags() const;

        /**

         * Sets the icon for the normal state. Takes ownership.

         *

         * @param aIcon The icon for the normal state.

         */

        IMPORT_C void SetIcon( CGulIcon* aIcon );

        /**

         * Sets the icon for the dimmed state. Takes ownership.

         *

         * @param aDimmedIcon The icon for the dimmed state.

         */

        IMPORT_C void SetDimmedIcon( CGulIcon* aDimmedIcon );

        /**

         * Sets the icon for the pressed down state. Takes ownership.

         *

         * @param aPressedIcon The icon for the pressed down state.

         */

        IMPORT_C void SetPressedIcon( CGulIcon* aPressedIcon );

        /**

         * Sets the icon for the hover state. Takes ownership.

         *

         * @param aHoverIcon The icon for the hover state.

         */

        IMPORT_C void SetHoverIcon( CGulIcon* aHoverIcon );

        /**

         * Sets the text inside the button.

         *

         * @param aText The text inside the button.

         */

        IMPORT_C void SetTextL( const TDesC& aText );

        /**

         * Sets the text inside the help note.

         *

         * @param aHelpText The text inside the tooltip.

         */

        IMPORT_C void SetHelpTextL( const TDesC& aHelpText );

        /**

         * Sets the flags for the state.

         *

         * @param aFlags The flags for the state.

         */

        IMPORT_C void SetFlags( const TInt aFlags );

        /**

         * Sets the icon for the normal state

         *

         * @param aFlags The flags for the state.

         */

        void UpdateIconL( const TDesC& aFilePath, 

                          const TInt aBmpId, 

                          const TInt aMaskId,

                          const TInt aDimmedBmpId, 

                          const TInt aDimmedMaskId,

                          const TInt aPressedBmpId, 

                          const TInt aPressedMaskId,

                          const TInt aHoverBmpId,

                          const TInt aHoverMaskId,

                          const TAknsItemID& aId = KAknsIIDNone, 

                          const TAknsItemID& aDimmedId = KAknsIIDNone, 

                          const TAknsItemID& aPressedId = KAknsIIDNone,

                          const TAknsItemID& aHoverId = KAknsIIDNone );

        /*

         * Update extension

         * @param aResource resource ID

         */

        void UpdateExtensionInfoL( TInt aResource );

    protected: // New functions

        /**

         * Constructs controls from a resource file.

         * @param aReader The resource reader with which to access the

         *          control's resource values.

         */

        IMPORT_C virtual void ConstructFromResourceL( TResourceReader& aReader );

        /**

         * Updates the size of icons. Called from CAknButton::SizeChanged() 

         * function.

         *

         * @param aRect The new rectangle for the icons.

         * @param aScaleMode The scale mode which was set for the button.

         */

        IMPORT_C virtual void SizeChanged( const TRect& aRect, 

                                           TScaleMode aScaleMode );

        /**

         * @return ETrue if the button has valid text (not empty and not space).

         */

        IMPORT_C TBool HasText() const;

        /**

         * @return ETrue if the button has valid tooltip text (not empty and 

         *          not space).

         */

        IMPORT_C TBool HasHelp() const;

        /**

        * Handles changes in state's environment.

        *

        * @since S60 3.2.

        * @param aType Resource change's type.

        */

        void HandleResourceChange( TInt aType );

        /**

        * Sets default scaling mode.

        *

        * @since S60 3.2

        * @param aScaleMode Scaling mode.

        */

        void SetIconScaleMode( const TScaleMode aScaleMode );

    private: // new functions

        /**

         * Creates one icon based on the specified file path and IDs.

         *

         * @param aIcon The icon object which is created and returned. 

         *      Will be deleted if it is not NULL on entry.

         * @param aFilePath The path to the file which contains icons.

         * @param aBmpId The bitmap ID for the icon.

         * @param aMaskId The mask ID for the icon.

         * @param aId Item ID of the masked bitmap to be created for skin 

         *      specific icon.

         */

        void CreateButtonIconL( CGulIcon*& aIcon, const TDesC& aFilePath, 

                                TInt aBmpId, TInt aMaskId, 

                                const TAknsItemID& aId = KAknsIIDNone ) const;

        /**

         * Loads one icon based on the specified file path and IDs. If the icon

         * is already loaded it is deleted and replaced with a reloaded copy.

         *

         * @since S60 3.2

         * @param aIcon The icon object which is created and returned. 

         *      Will be deleted if it is not NULL on entry.

         * @param aFilePath The path to the file which contains icons.

         * @param aBmpId The bitmap ID for the icon.

         * @param aMaskId The mask ID for the icon.

         * @param aId Item ID of the masked bitmap to be created for skin 

         *      specific icon.

         */

        void LoadButtonIcon( CGulIcon*& aIcon ) const;

        /**

         * Replaces the given icon with a new one. If the original icon had its

         * size set then the new icon is scaled to that size.

         *

         * @since S60 3.2

         */

        void ReplaceIcon( CGulIcon*& aIcon, CGulIcon* aNewIcon );

        /**

        * Scales all icons.

        *

        * @since S60 3.2

        * @param aSize New icon size.

        * @param aScaleMode Scaling mode.

        * @return KErrNone or an error code.

        */

        TInt ScaleIcons( const TSize& aSize, TScaleMode aScaleMode );

        /**

         * @return The extension object.

         */

        CAknButtonStateExtension* Extension() const;

        /**

         * @return The scalemode of the ButtonState

         */

        TScaleMode ScaleMode() const;

        /**

         * @param aDimmedIconCreatedByButton ETrue, if the dimmed icon of the state is 

         * created by owning Button

         */

        void SetGeneratedDimmedIcon( TBool aDimmedIconCreatedByButton );

        /**

         * Tells if frame update is needed, it is needed when the flag 

         * KAknButtonStateHasLatchedFrame has changed. 

         * @return ETrue if flag KAknButtonStateHasLatchedFrame has changed.

         */

        TBool FlagsChanged();

        /**

         * Frame has been updated. No need to update anymore. 

         */

        void ResetFlagsChanged();

        /**

         * Checks if text has changed. 

         * @return ETrue is state's text has changed. 

         */

        TBool TextChanged(); 

        /**

         * Visual text has been updated, so iTextChanged can be set to EFalse.

         */

        void ResetTextChanged(); 

        friend class CAknButton;

    protected: // data

        CGulIcon*   iIcon;                      // bitmaps for normal state

        CGulIcon*   iDimmedIcon;                // bitmaps for dimmed icon

        CGulIcon*   iPressedIcon;               // bitmaps for pressed but not activated state

        CGulIcon*   iHoverIcon;                 // bitmaps for hover icon

        HBufC*      iText;                      // text for normal state

        HBufC*      iHelpText;                  // text which is shown as a help

        TInt        iFlags;                     // flags for the state

        CAknButtonStateExtension* iExtension;   // for future extensions

    };

// CLASS DECLARATION

/**

*  Generic button class.

*

*  @lib eikcoctl.lib

*  @since Series 60 3.1

*/

class CAknButton : public CAknControl

    {

    public: // Enumerations

        enum TAlignment

            {

            ECenter, /* align center vertically or horizontally */

            ETop, /* align to top vertically */

            EBottom, /* align to bottom vertically */

            ERight, /* align to right horizontally */

            ELeft /* align to left horixontally */

            };

        enum TTooltipPosition

            {

            EPositionTop = 1, /* Tool tip alignment vertically to top */

            EPositionBottom, /* Tool tip alignment vertically to bottom */

            EPositionLeft, /* Tool tip alignment horizontally to left */

            EPositionRight /* Tool tip alignment horizontally to right */

            };

        enum TTextAndIconAlignment

            {

            EIconBeforeText, /* Icon and text side by side Icon first */

            EIconAfterText,  /* Icon and text side by side Text first */

            EIconUnderText,  /* Icon and text one upon the other Icon under the text */

            EIconOverText,   /* Icon and text one upon the other Icon over the text */

            EOverlay         /* Icon and text overlaid */

            };            

        enum TButtonEvent

            {

            ELongPressEvent = 100, /* Observer event for long press event */

            ELongPressEndedEvent   /* Observer event for long press ended event */

            };

    public: // Constructors and destructors

        /**

         * Two-phased constructor.

         * Constructs an empty button.

         */

        IMPORT_C static CAknButton* NewL();

        /**

         * Two-phased constructor. Constructs an empty button.

         */

        IMPORT_C static CAknButton* NewLC();

        /**

         * Two-phased constructor. Constructs the button from resources.

         *

         * @param aReader is the resource reader with which to access 

         *      the control's resource values.

         */

        IMPORT_C static CAknButton* NewL( TResourceReader& aReader );

        /**

         * Two-phased constructor. Constructs the button from resources.

         *

         * @param aReader is the resource reader with which to access 

         *      the control's resource values. 

         */

        IMPORT_C static CAknButton* NewLC( TResourceReader& aReader ); 

        /**

         * Two-phased constructor. Constructs the button from resources.

         * 

         * @param aResourceId is the ID for this component's resource.

         */

        IMPORT_C static CAknButton* NewL( const TInt aResourceId );

        /**

         * Two-phased constructor. Constructs the button from resources. 

         * 

         * @param aResourceId is the ID for this component's resource.

         */

        IMPORT_C static CAknButton* NewLC( const TInt aResourceId );

        /**

         * Two-phased constructor. Constructs one state button.

         *

         * @param aIcon The icon for the normal state. Takes ownership.

         * @param aDimmedIcon The icon for the dimmed state. Takes ownership.

         * @param aPressedIcon The icon for the pressed down. Takes ownership.

         * @param aHoverIcon The icon for the hover state. Takes ownership.

         * @param aText The text inside the button.

         * @param aHelpText The text for the tooltip.

         * @param aButtonFlags The flags for the button.

         * @param aStateFlags The flags for the first state.

         */

        IMPORT_C static CAknButton* NewL( CGulIcon* aIcon, 

                                          CGulIcon* aDimmedIcon,

                                          CGulIcon* aPressedIcon,

                                          CGulIcon* aHoverIcon,

                                          const TDesC& aText, 

                                          const TDesC& aHelpText, 

                                          const TInt aButtonFlags,

                                          const TInt aStateFlags );

        /**

         * Two-phased constructor. Constructs one state button.

         *

         * @param aIcon The icon for the normal state. Takes ownership.

         * @param aDimmedIcon The icon for the dimmed state. Takes ownership.

         * @param aPressedIcon The icon for the pressed down. Takes ownership.

         * @param aHoverIcon The icon for the hover state. Takes ownership.

         * @param aText The text inside the button.

         * @param aHelpText The text for the tooltip.

         * @param aButtonFlags The flags for the button.

         * @param aStateFlags The flags for the first state.

         */

        IMPORT_C static CAknButton* NewLC( CGulIcon* aIcon, 

                                           CGulIcon* aDimmedIcon,

                                           CGulIcon* aPressedIcon,

                                           CGulIcon* aHoverIcon,

                                           const TDesC& aText, 

                                           const TDesC& aHelpText, 

                                           const TInt aFlags,

                                           const TInt aStateFlags );

        /**

         * Two-phased constructor. Constructs one state button.

         *

         * @param aFilePath The path to the file which contains icons.