classicui_pub/generic_button_api/inc/AknButton.h
branchRCL_3
changeset 56 d48ab3b357f1
child 72 a5e7a4f63858
equal deleted inserted replaced
55:aecbbf00d063 56:d48ab3b357f1
       
     1 /*
       
     2 * Copyright (c) 2005-2008 Nokia Corporation and/or its subsidiary(-ies).
       
     3 * All rights reserved.
       
     4 * This component and the accompanying materials are made available
       
     5 * under the terms of "Eclipse Public License v1.0"
       
     6 * which accompanies this distribution, and is available
       
     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".
       
     8 *
       
     9 * Initial Contributors:
       
    10 * Nokia Corporation - initial contribution.
       
    11 *
       
    12 * Contributors:
       
    13 *
       
    14 * Description:  Button component.
       
    15 *
       
    16 */
       
    17 
       
    18 
       
    19 
       
    20 #ifndef __AKNBUTTON_H__
       
    21 #define __AKNBUTTON_H__
       
    22 
       
    23 //  INCLUDES
       
    24 #include <AknControl.h>
       
    25 #include <AknIconUtils.h>
       
    26 #include <AknUtils.h>
       
    27 
       
    28 // FORWARD DECLARATIONS
       
    29 class CGulIcon;
       
    30 class CAknButton;
       
    31 class CAknButtonExtension; 
       
    32 class CAknInfoPopupNoteController;
       
    33 class CAknButtonStateExtension;
       
    34 class CAknPictographInterface;
       
    35 class CAknsFrameBackgroundControlContext;
       
    36 class CAknResourceProvider;
       
    37 
       
    38 // CLASS DECLARATION
       
    39 
       
    40 /**
       
    41 *  Class which represents one of the button states. 
       
    42 *
       
    43 *  @lib eikcoctl.lib
       
    44 *  @since Series 60 3.1
       
    45 */
       
    46 class CAknButtonState : public CBase
       
    47     {           
       
    48     public: // Constructors and destructors
       
    49 
       
    50         /**
       
    51          * Destructor.
       
    52          */
       
    53         IMPORT_C ~CAknButtonState();
       
    54 
       
    55     protected: // Constructors and destructors
       
    56 
       
    57         /**
       
    58          * Constructor.
       
    59          *
       
    60          * @param aFlags The flags for the button state
       
    61          */
       
    62         IMPORT_C CAknButtonState( const TInt aFlags );
       
    63 
       
    64         /**
       
    65          * Symbian 2nd phase constructor.
       
    66          *
       
    67          * @param aIcon The icon for the normal state. Takes ownership.
       
    68          * @param aDimmedIcon The icon for the dimmed state. Takes ownership.
       
    69          * @param aPressedIcon The icon for the pressed down. Takes ownership.
       
    70          * @param aHoverIcon The icon for the hover state. Takes ownership.
       
    71          * @param aText The text inside the button.
       
    72          * @param aHelpText The text for the tooltip.
       
    73          */
       
    74         IMPORT_C void ConstructL( CGulIcon* aIcon,
       
    75                                   CGulIcon* aDimmedIcon, 
       
    76                                   CGulIcon* aPressedIcon,
       
    77                                   CGulIcon* aHoverIcon,
       
    78                                   const TDesC& aText, 
       
    79                                   const TDesC& aHelpText );
       
    80 
       
    81         /**
       
    82          * Symbian 2nd phase constructor.
       
    83          *
       
    84          * @param aFilePath The path to the file which contains icons.
       
    85          * @param aBmpId The bitmap ID for the normal state icon.
       
    86          * @param aMaskId The mask ID for the normal state icon.
       
    87          * @param aDimmedBmpId The bitmap ID for the dimmed state icon.
       
    88          * @param aDimmedMaskId The mask ID for the dimmed state icon.
       
    89          * @param aPressedBmpId The bitmap ID for the pressed down state.
       
    90          * @param aPressedMaskId The mask ID for the pressed down state.
       
    91          * @param aHoverBmpId The bitmap ID for the hover state icon.
       
    92          * @param aHoverMaskId The mask ID for the hover state icon.
       
    93          * @param aText The text inside the button.
       
    94          * @param aHelpText The text for the tooltip.
       
    95          * @param aId Item ID of the masked bitmap to be created for skin 
       
    96          *          specific icon.
       
    97          * @param aDimmedId Item ID of the dimmed masked bitmap to be created
       
    98          *          for skin specific icon.
       
    99          * @param aPressedId Item ID of the pressed masked bitmap to be created
       
   100          *          for skin specific icon.
       
   101          * @param aHoverId Item ID of the masked hover bitmap to be created
       
   102          *          for skin specific icon.
       
   103          */
       
   104         IMPORT_C void ConstructL( const TDesC& aFilePath, 
       
   105                                   const TInt aBmpId, 
       
   106                                   const TInt aMaskId,
       
   107                                   const TInt aDimmedBmpId, 
       
   108                                   const TInt aDimmedMaskId,
       
   109                                   const TInt aPressedBmpId, 
       
   110                                   const TInt aPressedMaskId,
       
   111                                   const TInt aHoverBmpId,
       
   112                                   const TInt aHoverMaskId,
       
   113                                   const TDesC& aText, 
       
   114                                   const TDesC& aHelpText,
       
   115                                   const TAknsItemID& aId = KAknsIIDNone, 
       
   116                                   const TAknsItemID& aDimmedId = KAknsIIDNone, 
       
   117                                   const TAknsItemID& aPressedId = KAknsIIDNone,
       
   118                                   const TAknsItemID& aHoverId = KAknsIIDNone );
       
   119 
       
   120     public: // New functions
       
   121 
       
   122         /**
       
   123          * Provides the icon for the normal state.
       
   124          *
       
   125          * @return The icon for the normal state.
       
   126          */
       
   127         IMPORT_C const CGulIcon* Icon() const;
       
   128 
       
   129         /**
       
   130          * Provides the icon for the dimmed state.
       
   131          *
       
   132          * @return The icon for the dimmed state.
       
   133          */
       
   134         IMPORT_C const CGulIcon* DimmedIcon() const;
       
   135 
       
   136         /**
       
   137          * Provides the icon for the pressed down (not released) state.
       
   138          *
       
   139          * @return The icon for the pressed down (not released) state.
       
   140          */
       
   141         IMPORT_C const CGulIcon* PressedIcon() const;
       
   142         
       
   143         /**
       
   144          * Provides the icon for the hover state.
       
   145          *
       
   146          * @return The icon for the hover state.
       
   147          */
       
   148         IMPORT_C const CGulIcon* HoverIcon() const;
       
   149 
       
   150         /**
       
   151          * Provides the text inside the button.
       
   152          *
       
   153          * @return The button text.
       
   154          */
       
   155         IMPORT_C const TDesC& Text() const;
       
   156 
       
   157         /**
       
   158          * Provides the text inside the help note.
       
   159          *
       
   160          * @return The tooltip text.
       
   161          */
       
   162         IMPORT_C const TDesC& HelpText() const;
       
   163 
       
   164         /**
       
   165          * Provides the flags for the state.
       
   166          *
       
   167          * @return The state flags.
       
   168          */
       
   169         IMPORT_C TInt Flags() const;
       
   170 
       
   171         /**
       
   172          * Sets the icon for the normal state. Takes ownership.
       
   173          *
       
   174          * @param aIcon The icon for the normal state.
       
   175          */
       
   176         IMPORT_C void SetIcon( CGulIcon* aIcon );
       
   177 
       
   178         /**
       
   179          * Sets the icon for the dimmed state. Takes ownership.
       
   180          *
       
   181          * @param aDimmedIcon The icon for the dimmed state.
       
   182          */
       
   183         IMPORT_C void SetDimmedIcon( CGulIcon* aDimmedIcon );
       
   184 
       
   185         /**
       
   186          * Sets the icon for the pressed down state. Takes ownership.
       
   187          *
       
   188          * @param aPressedIcon The icon for the pressed down state.
       
   189          */
       
   190         IMPORT_C void SetPressedIcon( CGulIcon* aPressedIcon );
       
   191 
       
   192         /**
       
   193          * Sets the icon for the hover state. Takes ownership.
       
   194          *
       
   195          * @param aHoverIcon The icon for the hover state.
       
   196          */
       
   197         IMPORT_C void SetHoverIcon( CGulIcon* aHoverIcon );
       
   198 
       
   199         /**
       
   200          * Sets the text inside the button.
       
   201          *
       
   202          * @param aText The text inside the button.
       
   203          */
       
   204         IMPORT_C void SetTextL( const TDesC& aText );
       
   205 
       
   206         /**
       
   207          * Sets the text inside the help note.
       
   208          *
       
   209          * @param aHelpText The text inside the tooltip.
       
   210          */
       
   211         IMPORT_C void SetHelpTextL( const TDesC& aHelpText );
       
   212 
       
   213         /**
       
   214          * Sets the flags for the state.
       
   215          *
       
   216          * @param aFlags The flags for the state.
       
   217          */
       
   218         IMPORT_C void SetFlags( const TInt aFlags );
       
   219         
       
   220         /**
       
   221          * Sets the icon for the normal state
       
   222          *
       
   223          * @param aFlags The flags for the state.
       
   224          */
       
   225         void UpdateIconL( const TDesC& aFilePath, 
       
   226                           const TInt aBmpId, 
       
   227                           const TInt aMaskId,
       
   228                           const TInt aDimmedBmpId, 
       
   229                           const TInt aDimmedMaskId,
       
   230                           const TInt aPressedBmpId, 
       
   231                           const TInt aPressedMaskId,
       
   232                           const TInt aHoverBmpId,
       
   233                           const TInt aHoverMaskId,
       
   234                           const TAknsItemID& aId = KAknsIIDNone, 
       
   235                           const TAknsItemID& aDimmedId = KAknsIIDNone, 
       
   236                           const TAknsItemID& aPressedId = KAknsIIDNone,
       
   237                           const TAknsItemID& aHoverId = KAknsIIDNone );
       
   238         
       
   239         /*
       
   240          * Update extension
       
   241          * @param aResource resource ID
       
   242          */
       
   243         void UpdateExtensionInfoL( TInt aResource );
       
   244         
       
   245     protected: // New functions
       
   246 
       
   247         /**
       
   248          * Constructs controls from a resource file.
       
   249          * @param aReader The resource reader with which to access the
       
   250          *          control's resource values.
       
   251          */
       
   252         IMPORT_C virtual void ConstructFromResourceL( TResourceReader& aReader );
       
   253 
       
   254         /**
       
   255          * Updates the size of icons. Called from CAknButton::SizeChanged() 
       
   256          * function.
       
   257          *
       
   258          * @param aRect The new rectangle for the icons.
       
   259          * @param aScaleMode The scale mode which was set for the button.
       
   260          */
       
   261         IMPORT_C virtual void SizeChanged( const TRect& aRect, 
       
   262                                            TScaleMode aScaleMode );
       
   263 
       
   264         /**
       
   265          * @return ETrue if the button has valid text (not empty and not space).
       
   266          */
       
   267         IMPORT_C TBool HasText() const;
       
   268 
       
   269         /**
       
   270          * @return ETrue if the button has valid tooltip text (not empty and 
       
   271          *          not space).
       
   272          */
       
   273         IMPORT_C TBool HasHelp() const;
       
   274         
       
   275         /**
       
   276         * Handles changes in state's environment.
       
   277         *
       
   278         * @since S60 3.2.
       
   279         * @param aType Resource change's type.
       
   280         */
       
   281         void HandleResourceChange( TInt aType );
       
   282         
       
   283         /**
       
   284         * Sets default scaling mode.
       
   285         *
       
   286         * @since S60 3.2
       
   287         * @param aScaleMode Scaling mode.
       
   288         */
       
   289         void SetIconScaleMode( const TScaleMode aScaleMode );
       
   290 
       
   291     private: // new functions
       
   292 
       
   293         /**
       
   294          * Creates one icon based on the specified file path and IDs.
       
   295          *
       
   296          * @param aIcon The icon object which is created and returned. 
       
   297          *      Will be deleted if it is not NULL on entry.
       
   298          * @param aFilePath The path to the file which contains icons.
       
   299          * @param aBmpId The bitmap ID for the icon.
       
   300          * @param aMaskId The mask ID for the icon.
       
   301          * @param aId Item ID of the masked bitmap to be created for skin 
       
   302          *      specific icon.
       
   303          */
       
   304         void CreateButtonIconL( CGulIcon*& aIcon, const TDesC& aFilePath, 
       
   305                                 TInt aBmpId, TInt aMaskId, 
       
   306                                 const TAknsItemID& aId = KAknsIIDNone ) const;
       
   307                                 
       
   308         /**
       
   309          * Loads one icon based on the specified file path and IDs. If the icon
       
   310          * is already loaded it is deleted and replaced with a reloaded copy.
       
   311          *
       
   312          * @since S60 3.2
       
   313          * @param aIcon The icon object which is created and returned. 
       
   314          *      Will be deleted if it is not NULL on entry.
       
   315          * @param aFilePath The path to the file which contains icons.
       
   316          * @param aBmpId The bitmap ID for the icon.
       
   317          * @param aMaskId The mask ID for the icon.
       
   318          * @param aId Item ID of the masked bitmap to be created for skin 
       
   319          *      specific icon.
       
   320          */
       
   321         void LoadButtonIcon( CGulIcon*& aIcon ) const;
       
   322                                 
       
   323         /**
       
   324          * Replaces the given icon with a new one. If the original icon had its
       
   325          * size set then the new icon is scaled to that size.
       
   326          *
       
   327          * @since S60 3.2
       
   328          */
       
   329         void ReplaceIcon( CGulIcon*& aIcon, CGulIcon* aNewIcon );
       
   330                           
       
   331         /**
       
   332         * Scales all icons.
       
   333         *
       
   334         * @since S60 3.2
       
   335         * @param aSize New icon size.
       
   336         * @param aScaleMode Scaling mode.
       
   337         * @return KErrNone or an error code.
       
   338         */
       
   339         TInt ScaleIcons( const TSize& aSize, TScaleMode aScaleMode );
       
   340 
       
   341         /**
       
   342          * @return The extension object.
       
   343          */
       
   344         CAknButtonStateExtension* Extension() const;
       
   345 
       
   346         /**
       
   347          * @return The scalemode of the ButtonState
       
   348          */
       
   349         TScaleMode ScaleMode() const;
       
   350         
       
   351         /**
       
   352          * @param aDimmedIconCreatedByButton ETrue, if the dimmed icon of the state is 
       
   353          * created by owning Button
       
   354          */
       
   355         void SetGeneratedDimmedIcon( TBool aDimmedIconCreatedByButton );
       
   356         
       
   357         /**
       
   358          * Tells if frame update is needed, it is needed when the flag 
       
   359          * KAknButtonStateHasLatchedFrame has changed. 
       
   360          * @return ETrue if flag KAknButtonStateHasLatchedFrame has changed.
       
   361          */
       
   362         TBool FlagsChanged();
       
   363 
       
   364         /**
       
   365          * Frame has been updated. No need to update anymore. 
       
   366          */
       
   367         void ResetFlagsChanged();
       
   368 
       
   369         /**
       
   370          * Checks if text has changed. 
       
   371          * @return ETrue is state's text has changed. 
       
   372          */
       
   373         TBool TextChanged(); 
       
   374         
       
   375         /**
       
   376          * Visual text has been updated, so iTextChanged can be set to EFalse.
       
   377          */
       
   378         void ResetTextChanged(); 
       
   379         
       
   380         friend class CAknButton;
       
   381 
       
   382     protected: // data
       
   383         CGulIcon*   iIcon;                      // bitmaps for normal state
       
   384         CGulIcon*   iDimmedIcon;                // bitmaps for dimmed icon
       
   385         CGulIcon*   iPressedIcon;               // bitmaps for pressed but not activated state
       
   386         CGulIcon*   iHoverIcon;                 // bitmaps for hover icon
       
   387         HBufC*      iText;                      // text for normal state
       
   388         HBufC*      iHelpText;                  // text which is shown as a help
       
   389         TInt        iFlags;                     // flags for the state
       
   390         CAknButtonStateExtension* iExtension;   // for future extensions
       
   391     };
       
   392 
       
   393 
       
   394 // CLASS DECLARATION
       
   395 
       
   396 /**
       
   397 *  Generic button class.
       
   398 *
       
   399 *  @lib eikcoctl.lib
       
   400 *  @since Series 60 3.1
       
   401 */
       
   402 class CAknButton : public CAknControl
       
   403     {
       
   404     public: // Enumerations
       
   405 
       
   406         enum TAlignment
       
   407             {
       
   408             ECenter, /* align center vertically or horizontally */
       
   409             ETop, /* align to top vertically */
       
   410             EBottom, /* align to bottom vertically */
       
   411             ERight, /* align to right horizontally */
       
   412             ELeft /* align to left horixontally */
       
   413             };
       
   414 
       
   415         enum TTooltipPosition
       
   416             {
       
   417             EPositionTop = 1, /* Tool tip alignment vertically to top */
       
   418             EPositionBottom, /* Tool tip alignment vertically to bottom */
       
   419             EPositionLeft, /* Tool tip alignment horizontally to left */
       
   420             EPositionRight /* Tool tip alignment horizontally to right */
       
   421             };
       
   422             
       
   423         enum TTextAndIconAlignment
       
   424             {
       
   425             EIconBeforeText, /* Icon and text side by side Icon first */
       
   426             EIconAfterText,  /* Icon and text side by side Text first */
       
   427             EIconUnderText,  /* Icon and text one upon the other Icon under the text */
       
   428             EIconOverText,   /* Icon and text one upon the other Icon over the text */
       
   429             EOverlay         /* Icon and text overlaid */
       
   430             };            
       
   431 
       
   432         enum TButtonEvent
       
   433             {
       
   434             ELongPressEvent = 100, /* Observer event for long press event */
       
   435             ELongPressEndedEvent   /* Observer event for long press ended event */
       
   436             };
       
   437 
       
   438     public: // Constructors and destructors
       
   439     
       
   440         /**
       
   441          * Two-phased constructor.
       
   442          * Constructs an empty button.
       
   443          */
       
   444         IMPORT_C static CAknButton* NewL();
       
   445         
       
   446         /**
       
   447          * Two-phased constructor. Constructs an empty button.
       
   448          */
       
   449         IMPORT_C static CAknButton* NewLC();
       
   450         
       
   451         /**
       
   452          * Two-phased constructor. Constructs the button from resources.
       
   453          *
       
   454          * @param aReader is the resource reader with which to access 
       
   455          *      the control's resource values.
       
   456          */
       
   457         IMPORT_C static CAknButton* NewL( TResourceReader& aReader );
       
   458         
       
   459         /**
       
   460          * Two-phased constructor. Constructs the button from resources.
       
   461          *
       
   462          * @param aReader is the resource reader with which to access 
       
   463          *      the control's resource values. 
       
   464          */
       
   465         IMPORT_C static CAknButton* NewLC( TResourceReader& aReader ); 
       
   466         
       
   467         /**
       
   468          * Two-phased constructor. Constructs the button from resources.
       
   469          * 
       
   470          * @param aResourceId is the ID for this component's resource.
       
   471          */
       
   472         IMPORT_C static CAknButton* NewL( const TInt aResourceId );
       
   473         
       
   474         /**
       
   475          * Two-phased constructor. Constructs the button from resources. 
       
   476          * 
       
   477          * @param aResourceId is the ID for this component's resource.
       
   478          */
       
   479         IMPORT_C static CAknButton* NewLC( const TInt aResourceId );
       
   480 
       
   481         /**
       
   482          * Two-phased constructor. Constructs one state button.
       
   483          *
       
   484          * @param aIcon The icon for the normal state. Takes ownership.
       
   485          * @param aDimmedIcon The icon for the dimmed state. Takes ownership.
       
   486          * @param aPressedIcon The icon for the pressed down. Takes ownership.
       
   487          * @param aHoverIcon The icon for the hover state. Takes ownership.
       
   488          * @param aText The text inside the button.
       
   489          * @param aHelpText The text for the tooltip.
       
   490          * @param aButtonFlags The flags for the button.
       
   491          * @param aStateFlags The flags for the first state.
       
   492          */
       
   493         IMPORT_C static CAknButton* NewL( CGulIcon* aIcon, 
       
   494                                           CGulIcon* aDimmedIcon,
       
   495                                           CGulIcon* aPressedIcon,
       
   496                                           CGulIcon* aHoverIcon,
       
   497                                           const TDesC& aText, 
       
   498                                           const TDesC& aHelpText, 
       
   499                                           const TInt aButtonFlags,
       
   500                                           const TInt aStateFlags );
       
   501 
       
   502         /**
       
   503          * Two-phased constructor. Constructs one state button.
       
   504          *
       
   505          * @param aIcon The icon for the normal state. Takes ownership.
       
   506          * @param aDimmedIcon The icon for the dimmed state. Takes ownership.
       
   507          * @param aPressedIcon The icon for the pressed down. Takes ownership.
       
   508          * @param aHoverIcon The icon for the hover state. Takes ownership.
       
   509          * @param aText The text inside the button.
       
   510          * @param aHelpText The text for the tooltip.
       
   511          * @param aButtonFlags The flags for the button.
       
   512          * @param aStateFlags The flags for the first state.
       
   513          */
       
   514         IMPORT_C static CAknButton* NewLC( CGulIcon* aIcon, 
       
   515                                            CGulIcon* aDimmedIcon,
       
   516                                            CGulIcon* aPressedIcon,
       
   517                                            CGulIcon* aHoverIcon,
       
   518                                            const TDesC& aText, 
       
   519                                            const TDesC& aHelpText, 
       
   520                                            const TInt aFlags,
       
   521                                            const TInt aStateFlags );
       
   522 
       
   523         /**
       
   524          * Two-phased constructor. Constructs one state button.
       
   525          *
       
   526          * @param aFilePath The path to the file which contains icons.
       
   527          * @param aBmpId The bitmap ID for the normal state icon.
       
   528          * @param aMaskId The mask ID for the normal state icon.
       
   529          * @param aDimmedBmpId The bitmap ID for the dimmed state icon.
       
   530          * @param aDimmedMaskId The mask ID for the dimmed state icon.
       
   531          * @param aPressedBmpId The bitmap ID for the pressed down state.
       
   532          * @param aPressedMaskId The mask ID for the pressed down state.
       
   533          * @param aHoverBmpId The bitmap ID for the hover state.
       
   534          * @param aHoverMaskId The mask ID for the hover state.
       
   535          * @param aText The text inside the button.
       
   536          * @param aHelpText The text for the tooltip.
       
   537          * @param aButtonFlags The flags for the button.
       
   538          * @param aStateFlags The flags for the first state.
       
   539          * @param aId Item ID of the masked bitmap to be created for skin 
       
   540          *      specific icon.
       
   541          * @param aDimmedId Item ID of the dimmed masked bitmap to be created 
       
   542          *      for skin specific icon.
       
   543          * @param aPressedId Item ID of the pressed masked bitmap to be created 
       
   544          *      for skin specific icon.
       
   545          * @param aHoverId Item ID of the masked hover bitmap to be created
       
   546          *      for skin specific icon.
       
   547          */
       
   548         IMPORT_C static CAknButton* NewL( const TDesC& aFilePath, 
       
   549                                           const TInt aBmpId, 
       
   550                                           const TInt aMaskId,
       
   551                                           const TInt aDimmedBmpId, 
       
   552                                           const TInt aDimmedMaskId,
       
   553                                           const TInt aPressedBmpId, 
       
   554                                           const TInt aPressedMaskId,
       
   555                                           const TInt aHoverBmpId,
       
   556                                           const TInt aHoverMaskId,
       
   557                                           const TDesC& aText, 
       
   558                                           const TDesC& aHelpText, 
       
   559                                           const TInt aButtonFlags, 
       
   560                                           const TInt aStateFlags,
       
   561                                           const TAknsItemID& aId = KAknsIIDNone, 
       
   562                                           const TAknsItemID& aDimmedId = KAknsIIDNone, 
       
   563                                           const TAknsItemID& aPressedId = KAknsIIDNone,
       
   564                                           const TAknsItemID& aHoverId = KAknsIIDNone );
       
   565 
       
   566         /**
       
   567          * Two-phased constructor. Constructs one state button.
       
   568          *
       
   569          * @param aFilePath The path to the file which contains icons.
       
   570          * @param aBmpId The bitmap ID for the normal state icon.
       
   571          * @param aMaskId The mask ID for the normal state icon.
       
   572          * @param aDimmedBmpId The bitmap ID for the dimmed state icon.
       
   573          * @param aDimmedMaskId The mask ID for the dimmed state icon.
       
   574          * @param aPressedBmpId The bitmap ID for the pressed down state.
       
   575          * @param aPressedMaskId The mask ID for the pressed down state.
       
   576          * @param aHoverBmpId The bitmap ID for the hover state.
       
   577          * @param aHoverMaskId The mask ID for the hover state.
       
   578          * @param aText The text inside the button.
       
   579          * @param aHelpText The text for the tooltip.
       
   580          * @param aButtonFlags The flags for the button.
       
   581          * @param aStateFlags The flags for the first state.
       
   582          * @param aId Item ID of the masked bitmap to be created for skin 
       
   583          *      specific icon.
       
   584          * @param aDimmedId Item ID of the dimmed masked bitmap to be created 
       
   585          *      for skin specific icon.
       
   586          * @param aPressedId Item ID of the pressed masked bitmap to be created 
       
   587          *      for skin specific icon.
       
   588          * @param aHoverId Item ID of the hover state masked bitmap to be
       
   589          *      created for skin specific icon.
       
   590          */
       
   591         IMPORT_C static CAknButton* NewLC( const TDesC& aFilePath, 
       
   592                                            const TInt aBmpId, 
       
   593                                            const TInt aMaskId,
       
   594                                            const TInt aDimmedBmpId, 
       
   595                                            const TInt aDimmedMaskId,
       
   596                                            const TInt aPressedBmpId, 
       
   597                                            const TInt aPressedMaskId, 
       
   598                                            const TInt aHoverBmpId,
       
   599                                            const TInt aHoverMaskId,
       
   600                                            const TDesC& aText, 
       
   601                                            const TDesC& aHelpText, 
       
   602                                            const TInt aButtonFlags, 
       
   603                                            const TInt aStateFlags,
       
   604                                            const TAknsItemID& aId = KAknsIIDNone, 
       
   605                                            const TAknsItemID& aDimmedId = KAknsIIDNone, 
       
   606                                            const TAknsItemID& aPressedId = KAknsIIDNone,
       
   607                                            const TAknsItemID& aHoverId = KAknsIIDNone );
       
   608 
       
   609         /**
       
   610          * Destructor.
       
   611          */
       
   612         IMPORT_C virtual ~CAknButton();
       
   613 
       
   614     public: // Functions from base class
       
   615 
       
   616         /**
       
   617          * Sets control as ready to be drawn.
       
   618          */
       
   619         IMPORT_C void ActivateL();
       
   620 
       
   621         /**
       
   622          * Constructs controls from a resource file.
       
   623          *
       
   624          * @param aReader The resource reader, with which to access the 
       
   625          *      control's resource values.
       
   626          */
       
   627         IMPORT_C void ConstructFromResourceL( TResourceReader& aReader );
       
   628 
       
   629         /**
       
   630          * Handles a change to the control's resources.
       
   631          *
       
   632          * @param aType is a message UID value.
       
   633          */
       
   634         IMPORT_C void HandleResourceChange( TInt aType );
       
   635 
       
   636         /**
       
   637          * Returns the control's minimum required size. It does not include the
       
   638          * size of the highlight. However, it includes current margins.
       
   639          * Use HighlightRect() function to get highlight rectangle for the 
       
   640          * focused button.
       
   641          *
       
   642          * @return The minimum size required by the control.
       
   643          */
       
   644         IMPORT_C TSize MinimumSize();
       
   645 
       
   646         /**
       
   647          * Sets button dimmed. Does not redraw the button. Note: This function
       
   648          * does not affect the flag set with function CCoeControl::SetDimmed(),
       
   649          * since button needs to get pointer events, even if it is dimmed.
       
   650          * The value of the flag can be enquired using CAknButotn::IsDimmed().
       
   651          *
       
   652          * @param aDimmed is ETrue to dim the button, EFalse to set the button 
       
   653          *      as not dimmed.
       
   654          */
       
   655         IMPORT_C void SetDimmed( TBool aDimmed );
       
   656 
       
   657         /**
       
   658          * Handles key events.
       
   659          *
       
   660          * @param aKeyEvent The key event.
       
   661          * @param aType The type of key event: EEventKey, EEventKeyUp or 
       
   662          *      EEventKeyDown.
       
   663          */
       
   664         IMPORT_C TKeyResponse OfferKeyEventL( const TKeyEvent& aKeyEvent, 
       
   665                                               TEventCode aType );
       
   666         
       
   667         /**
       
   668          * Sets this control as visible or invisible.
       
   669          *
       
   670          * @param aVisible ETrue to make the control visible, EFalse to make 
       
   671          *      it invisible.
       
   672          */
       
   673         IMPORT_C void MakeVisible( TBool aVisible );
       
   674 
       
   675         /**
       
   676          * This function is called by the dialog framework immediately before 
       
   677          * it removes keyboard focus from a control within a dialog.
       
   678          * Currently has empty implementation.
       
   679          */
       
   680         IMPORT_C void PrepareForFocusLossL();
       
   681 
       
   682         /**
       
   683          * Prepares the control for gaining focus.
       
   684          * Must be used before calling SetFocus() function in case when help 
       
   685          * note should be shown.
       
   686          */
       
   687         IMPORT_C void PrepareForFocusGainL(); 
       
   688 
       
   689         /**
       
   690          * Handles pointer events.
       
   691          *
       
   692          * @param aPointerEvent The pointer event.
       
   693          */
       
   694         IMPORT_C void HandlePointerEventL( const TPointerEvent& aPointerEvent );
       
   695 
       
   696         /**
       
   697          * Responds to changes in the position of a control.
       
   698          */
       
   699         IMPORT_C virtual void PositionChanged();  
       
   700 
       
   701     public: // New functions
       
   702 
       
   703         /**
       
   704          * Constructs controls from a resource file.
       
   705          *
       
   706          * @param aResourceId The ID for this component's resource.
       
   707          */
       
   708         IMPORT_C void ConstructFromResourceL( const TInt aResourceId );
       
   709 
       
   710         /**
       
   711          * Sets button state.
       
   712          *
       
   713          * @param aStateIndex The index for the state, starts from 0.
       
   714          * @param aDrawNow ETrue to redraw the button.
       
   715          */
       
   716         IMPORT_C virtual void SetCurrentState( const TInt aStateIndex, 
       
   717                                                const TBool aDrawNow );
       
   718 
       
   719         /**
       
   720          * Adds one more state for the button to the end of state array.
       
   721          *
       
   722          * @param aIcon The icon object containing a bitmap and a mask (if 
       
   723          *      there is one) for the button.
       
   724          * @param aDimmedIcon The icon object containing a bitmap and a mask 
       
   725          *      (if there is one) for the dimmed case.
       
   726          * @param aPressedIcon The icon object containing a bitmap and a mask
       
   727          *      (if there is one) for the case when button is pressed.
       
   728          * @param aHoverIcon The icon object containingg a bitmap and a mask
       
   729          *      for the case when the pointer is hovering over the button.
       
   730          * @param aText is the text.
       
   731          * @param aHelpText is the text for the tooltip.
       
   732          * @param aStateFlags The flags for the state.
       
   733          */
       
   734         IMPORT_C virtual void AddStateL( CGulIcon* aIcon, 
       
   735                                          CGulIcon* aDimmedIcon, 
       
   736                                          CGulIcon* aPressedIcon,
       
   737                                          CGulIcon* aHoverIcon,
       
   738                                          const TDesC& aText, 
       
   739                                          const TDesC& aHelpText, 
       
   740                                          const TInt aStateFlags );
       
   741 
       
   742         /**
       
   743          * Adds one more state for the button.
       
   744          *
       
   745          * @param aFilePath The path to the file which contains icons.
       
   746          * @param aBmpId The bitmap ID for the normal state icon.
       
   747          * @param aMaskId The mask ID for the normal state icon.
       
   748          * @param aDimmedBmpId The bitmap ID for the dimmed state icon.
       
   749          * @param aDimmedMaskId The mask ID for the dimmed state icon.
       
   750          * @param aPressedBmpId The bitmap ID for the pressed down state.
       
   751          * @param aPressedMaskId The mask ID for the pressed down state.
       
   752          * @param aHoverBmpId The bitmap ID for the hover state.
       
   753          * @param aHoverMaskId The mask ID for the hover state.
       
   754          * @param aHoverId Item ID of the hover state masked bitmap to be
       
   755          *      created for skin specific icon.
       
   756          * @param aText is the text.
       
   757          * @param aHelpText is the text for the tooltip.
       
   758          * @param aStateFlags The flags for the state.
       
   759          * @param aId Item ID of the masked bitmap to be created for skin 
       
   760          *      specific icon. Use KAknsIIDNone when it is not needed.
       
   761          * @param aDimmedId Item ID of the dimmed masked bitmap to be created 
       
   762          *      for skin specific icon. Use KAknsIIDNone when it is not needed.
       
   763          * @param aPressedId Item ID of the pressed masked bitmap to be created 
       
   764          *      for skin specific icon. Use KAknsIIDNone when it is not needed.
       
   765          * @param aHoverId Item ID of the hover state masked bitmap to be
       
   766          *      created for skin specific icon.
       
   767          */
       
   768         IMPORT_C virtual void AddStateL( const TDesC& aFilePath, 
       
   769                                          const TInt aBmpId, 
       
   770                                          const TInt aMaskId,
       
   771                                          const TInt aDimmedBmpId, 
       
   772                                          const TInt aDimmedMaskId,
       
   773                                          const TInt aPressedBmpId, 
       
   774                                          const TInt aPressedMaskId, 
       
   775                                          const TInt aHoverBmpId,
       
   776                                          const TInt aHoverMaskId,
       
   777                                          const TDesC& aText,
       
   778                                          const TDesC& aHelpText,
       
   779                                          const TInt aStateFlags,
       
   780                                          const TAknsItemID& aId, 
       
   781                                          const TAknsItemID& aDimmedId, 
       
   782                                          const TAknsItemID& aPressedId,
       
   783                                          const TAknsItemID& aHoverId );
       
   784         
       
   785         /**
       
   786          * Adds one more state for the button to the end of state array.
       
   787          *
       
   788          * @param  aIcon         The icon object containing a bitmap and
       
   789          *                       a mask (if there is one) for the button.
       
   790          * @param  aDimmedIcon   The icon object containing a bitmap and a mask 
       
   791          *                       (if there is one) for the dimmed case.
       
   792          * @param  aPressedIcon  The icon object containing a bitmap and a mask
       
   793          *                       (if there is one) for the case when
       
   794          *                       button is pressed.
       
   795          * @param  aHoverIcon    The icon object containingg a bitmap and
       
   796          *                       a mask for the case when the pointer is
       
   797          *                       hovering over the button.
       
   798          * @param  aText         is the text.
       
   799          * @param  aHelpText     is the text for the tooltip.
       
   800          * @param  aStateFlags   The flags for the state.
       
   801          * @param  aCommandId    Command to be attached with the state.
       
   802          */
       
   803         void AddStateL( CGulIcon* aIcon, 
       
   804                         CGulIcon* aDimmedIcon, 
       
   805                         CGulIcon* aPressedIcon,
       
   806                         CGulIcon* aHoverIcon,
       
   807                         const TDesC& aText, 
       
   808                         const TDesC& aHelpText, 
       
   809                         const TInt aStateFlags,
       
   810                         const TInt aCommandId );
       
   811 
       
   812         /**
       
   813          * Sets the button flags.
       
   814          *
       
   815          * @param aFlags which can be combination of: KAknButtonTextLeft, 
       
   816          *      KAknButtonSizeFitText, KAknButtonNoFrame, KAknButtonKeyRepeat,
       
   817          *      KAknButtonReportOnKeyDown, KAknButtonNoFramePressEvent,
       
   818          *      KAknButtonRequestExitOnButtonUpEvent, KAknButtonReportOnLongPress.
       
   819          */
       
   820         IMPORT_C void SetButtonFlags( const TInt aFlags );
       
   821 
       
   822         /** 
       
   823          * Sets specified frame IDs. Can be used when default frame is not 
       
   824          * suitable. Use KAknsIIDNone value in case when some frame or center
       
   825          * drawing is not needed or KAknsIIDDefault when the default button
       
   826          * frame should be used.
       
   827          *
       
   828          * @param aFrameId The item ID of the entire frame.
       
   829          * @param aCenterId The item ID of the center part of the frame.
       
   830          * @param aLatchedFrameId The item ID of the entire frame for button 
       
   831          *      in latched state.
       
   832          * @param aLatchedCenterId The item ID of the center part of the 
       
   833          *      frame for button in latched state.
       
   834          * @param aDimmedFrameId The item ID of the entire frame for a button
       
   835          *      in dimmed state.
       
   836          * @param aDimmedCenterId The item ID of the center part of the frame
       
   837          *      for a button in dimmed state.
       
   838          * @param aPressedFrameId The item ID of the entire frame for a 
       
   839          *      button in pressed state.
       
   840          * @param aPressedCenterId is the item ID of the center part of the 
       
   841          *      frame for a button in pressed state.
       
   842          * @param aLatchedDimmedFrameId The item ID of the entire frame for 
       
   843          *      a button in latched and dimmed state.
       
   844          * @param aLatchedDimmedCenterId The item ID of the center part of 
       
   845          *      the frame for a button in latched and dimmed state.
       
   846          */
       
   847         IMPORT_C void SetFrameAndCenterIds( const TAknsItemID& aFrameId, 
       
   848                                             const TAknsItemID& aCenterId,
       
   849                                             const TAknsItemID& aLatchedFrameId, 
       
   850                                             const TAknsItemID& aLatchedCenterId,
       
   851                                             const TAknsItemID& aDimmedFrameId, 
       
   852                                             const TAknsItemID& aDimmedCenterId,
       
   853                                             const TAknsItemID& aPressedFrameId, 
       
   854                                             const TAknsItemID& aPressedCenterId,
       
   855                                             const TAknsItemID& aLatchedDimmedFrameId, 
       
   856                                             const TAknsItemID& aLatchedDimmedCenterId );
       
   857 
       
   858         /** 
       
   859          * Sets specified background IDs. Can be used when default frame is not
       
   860          * suitable and the backgound is composed of only single image instead
       
   861          * of frame and center. SetFrameAndCenterIds() function can also be used
       
   862          * for this purpose by giving the same backround ID for both frame and
       
   863          * center. This allows also some of the states to be composed of frames
       
   864          * and the others from single backgound images. Use KAknsIIDNone value
       
   865          * in case when some backgound drawing is not needed or KAknsIIDDefault
       
   866          * when the default button frame should be used.
       
   867          *
       
   868          * @param aBackgroundId The item ID of the entire frame.
       
   869          * @param aLatchedBackgroundId The item ID of the background for the
       
   870          *      button in latched state.
       
   871          * @param aDimmedBackgroundId The item ID of the background for the
       
   872          *      button in dimmed state.
       
   873          * @param aPressedBackgroundId The item ID of the background for the 
       
   874          *      button in pressed state.
       
   875          * @param aLatchedDimmedBackgroundId The item ID of the background for 
       
   876          *      the button in latched and dimmed state.
       
   877          */
       
   878         IMPORT_C void SetBackgroundIds( const TAknsItemID& aBackgroundId, 
       
   879                                         const TAknsItemID& aLatchedBackgroundId, 
       
   880                                         const TAknsItemID& aDimmedBackgroundId, 
       
   881                                         const TAknsItemID& aPressedBackgroundId, 
       
   882                                         const TAknsItemID& aLatchedDimmedBackgroundId );
       
   883 
       
   884         /**
       
   885          * Sets some specific text font.
       
   886          *
       
   887          * @param aFont The font, which should be used for the text inside the 
       
   888          *      text button.
       
   889          */
       
   890         IMPORT_C void SetTextFont( const CFont* aFont );
       
   891 
       
   892         /**
       
   893          * Sets the color table and color index for the button text. It will be
       
   894          * used on button drawing, if color of the text shouldn't be taken from
       
   895          * text layout.
       
   896          *
       
   897          * @param aTextColorTableId Id for the color table 
       
   898          * @param aTextColorIndex Index of the color inside color table.
       
   899          */
       
   900         IMPORT_C void SetTextColorIds( const TAknsItemID& aTextColorTableId, 
       
   901                                        const TInt aTextColorIndex );
       
   902 
       
   903         /**
       
   904          * Sets the horizontal alignment for the text inside the button. It
       
   905          * will be used, if alignment shouldn't be taken from text layout. By
       
   906          * default it will be centered.
       
   907          *
       
   908          * @param aHorizontalAlignment The horizontal alignment for the text.
       
   909          */
       
   910         IMPORT_C void SetTextHorizontalAlignment( 
       
   911             const CGraphicsContext::TTextAlign aHorizontalAlignment );
       
   912 
       
   913         /**
       
   914          * Sets the vertical alignment for the text inside the button. It will 
       
   915          * be used if alignment shouldn't be taken from text layout. By default 
       
   916          * it will be centered.
       
   917          *
       
   918          * @param aVerticalAlignment The vertical alignment for the text.
       
   919          */
       
   920         IMPORT_C void SetTextVerticalAlignment( 
       
   921             const CAknButton::TAlignment aVerticalAlignment );
       
   922 
       
   923         /**
       
   924          * Sets the icon and text alignment for a button having both
       
   925          *
       
   926          * @param aAlignment. TTextAndIconAlignment
       
   927          */
       
   928         IMPORT_C void SetTextAndIconAlignment( 
       
   929             const CAknButton::TTextAndIconAlignment aAlignment );
       
   930 
       
   931         /**
       
   932          * Sets the text underline style for the text inside the button. By
       
   933          * default no underline is used.
       
   934          *
       
   935          * @param aUnderlineStyle The style of underline.
       
   936          */
       
   937         IMPORT_C void SetTextUnderlineStyle( TFontUnderline aUnderlineStyle );
       
   938 
       
   939         /**
       
   940          * Sets the scale mode for the icon inside the button. 
       
   941          * The default is EAspectRatioNotPreserved.
       
   942          *
       
   943          * @param aScaleMode The scale mode.
       
   944          */
       
   945         IMPORT_C void SetIconScaleMode( const TScaleMode aScaleMode );
       
   946 
       
   947         /**
       
   948          * Sets the horizontal alignment for the icon inside the button.
       
   949          * By default it will be centered.
       
   950          *
       
   951          * @param aHorizontalAlignment The horizontal alignment for the icon.
       
   952          */
       
   953         IMPORT_C void SetIconHorizontalAlignment( 
       
   954             const CAknButton::TAlignment aHorizontalAlignment );
       
   955 
       
   956         /**
       
   957          * Sets the vertical alignment for the icon inside the button.
       
   958          * By default it will be centered.
       
   959          *
       
   960          * @param aVerticalAlignment The vertical alignment for the icon.
       
   961          */
       
   962         IMPORT_C void SetIconVerticalAlignment( 
       
   963             const CAknButton::TAlignment aVerticalAlignment );
       
   964             
       
   965         /**
       
   966          * Sets the delay before the help text is shown and also specifies the 
       
   967          * time for how long help text is visible.
       
   968          *
       
   969          * @param aBeforeTimeout The delay in milliseconds before text help note 
       
   970          *      is shown. The default is 150 milliseconds.
       
   971          * @param aInViewTimeout The interval in milliseconds during which help 
       
   972          *      text note is shown. The default is 3000 milliseconds.
       
   973          */
       
   974         IMPORT_C void SetHelpNoteTimeouts( const TInt aBeforeTimeout, 
       
   975                                            const TInt aInViewTimeout );
       
   976 
       
   977         /**
       
   978          * Sets the interval for key repeat.
       
   979          *
       
   980          * @param aKeyRepeatDelay The initial delay, after which the key repeat is
       
   981                 started. The default is 500 milliseconds.
       
   982          * @param aKeyRepeatInterval The interval in milliseconds, in which key
       
   983          *      repeat events should be reported. The default is 500 milliseconds.
       
   984          */
       
   985         IMPORT_C void SetKeyRepeatInterval( const TInt aKeyRepeatDelay, 
       
   986                                             const TInt aKeyRepeatInterval );
       
   987         
       
   988         /**
       
   989          * Sets the interval for long press. When KAknButtonReportOnLongPress
       
   990          * flag is set for the button, button will notify observer with 
       
   991          * KAknButtonLongPressEvent as the event type, after button has been
       
   992          * pressed for the specified time.
       
   993          * 
       
   994          * @param aLongPressInterval The time interval in milliseconds, after
       
   995          *      which the long press event should be reported. The default
       
   996          *      value is 800 milliseconds.
       
   997          */
       
   998         IMPORT_C void SetLongPressInterval( const TInt aLongPressInterval );
       
   999 
       
  1000         /**
       
  1001          * Returns the index of the button state.
       
  1002          */
       
  1003         IMPORT_C TInt StateIndex() const;
       
  1004 
       
  1005         /**
       
  1006          * Enables pictograph drawing in the button text.
       
  1007          * Only effective in Japanese variant.
       
  1008          * By default, it is disabled.
       
  1009          *
       
  1010          * @param aInterface Used pictograph interface owned by the caller.
       
  1011          */
       
  1012         IMPORT_C void EnablePictographsL( CAknPictographInterface& aInterface );
       
  1013 
       
  1014         /**
       
  1015          * Disables pictograph drawing in the button text.
       
  1016          * Only effective in Japanese variant.
       
  1017          * By default, it is disabled.
       
  1018          */
       
  1019         IMPORT_C void DisablePictographs();
       
  1020 
       
  1021         /**
       
  1022          * It will change the default highlight rectangle around 
       
  1023          * the focused button.
       
  1024          *
       
  1025          * @param aRect The highlight rectangle.
       
  1026          */
       
  1027         IMPORT_C void SetHighlightRect( const TRect& aRect );
       
  1028 
       
  1029         /**
       
  1030          * Gets the highlight rectangle around the button.
       
  1031          *
       
  1032          * @return The higlight rectangle around the button.
       
  1033          */
       
  1034         IMPORT_C TRect HighlightRect() const;
       
  1035 
       
  1036         /**
       
  1037          * Sets the tooltip position.
       
  1038          *
       
  1039          * @param aPosition The position of the tooltip.
       
  1040          */
       
  1041         IMPORT_C void SetTooltipPosition( const TTooltipPosition aPosition );
       
  1042 
       
  1043         /**
       
  1044          * Sets whether button should send an EEventRequestExit event to command
       
  1045          * observer on button up event.
       
  1046          *
       
  1047          * @param aRequestExit ETrue if button should request exit.
       
  1048          */
       
  1049         IMPORT_C void SetRequestExit( const TBool aRequestExit );
       
  1050 
       
  1051         /**
       
  1052          * Tests if the control is dimmed. This function overrides the function
       
  1053          * declared in CCoeControl, and returns the value which is set and unset
       
  1054          * using CAknButton::SetDimmed().
       
  1055          *
       
  1056          * @return ETrue if the control is dimmed, EFalse if it is not dimmed.
       
  1057          */
       
  1058         IMPORT_C TBool IsDimmed() const;
       
  1059 
       
  1060         /**
       
  1061          * Sets the help text for dimmed button.
       
  1062          *
       
  1063          * @param aHelpText The text inside the tooltip.
       
  1064          */
       
  1065         IMPORT_C void SetDimmedHelpTextL( const TDesC& aHelpText );
       
  1066 
       
  1067         /**
       
  1068          * Check if point is within buttons visible area, when
       
  1069          * KAknButtonHitTest flag is enabled
       
  1070          *
       
  1071          * @param aPoint Location to check.
       
  1072          * @param aCheckHitArea if need to check the hit area for fixed 
       
  1073          *        toolbar button
       
  1074          */
       
  1075         TBool HitAreaContainsL( const TPoint& aPoint, TBool aCheckHitArea ) const; 
       
  1076         
       
  1077         /**
       
  1078          * Returns the current state of the button.
       
  1079          *
       
  1080          * @return the current state of the button
       
  1081          */
       
  1082         IMPORT_C CAknButtonState* State() const;
       
  1083 
       
  1084         /**
       
  1085          * Returns the state of the button under specified index.
       
  1086          *
       
  1087          * @param aStateIndex The index for the state.
       
  1088          * @return the state of the button.
       
  1089          */
       
  1090         IMPORT_C CAknButtonState* State( const TInt aStateIndex ) const;
       
  1091 
       
  1092         /**
       
  1093          * Returns the flags of button. The flags are defined in eikon.hrh.
       
  1094          * @return Button flags.
       
  1095          * @since S60 3.2
       
  1096          */
       
  1097         IMPORT_C TInt ButtonFlags() const;
       
  1098 
       
  1099         /**
       
  1100         * Sets button's margins. These define the free area inside the button
       
  1101         * where content is placed. Note that calling this function overrides
       
  1102         * default margins that are scaled automatically depending on the 
       
  1103         * current screen layout. If this function is called then the caller
       
  1104         * is responsible for updating margins whenever the layout changes.
       
  1105         *
       
  1106         * @since S60 3.2
       
  1107         * @param aMargins New marginals.
       
  1108         */
       
  1109         IMPORT_C void SetMargins( const TMargins8& aMargins );
       
  1110         
       
  1111         /**
       
  1112         * Sets icon size for the button. Calling this function overrides the
       
  1113         * default size that is scaled automatically depending on the current
       
  1114         * screen layout. If this function is called then the caller is
       
  1115         * responsible for updating icon size whenever the layout changes.
       
  1116         *
       
  1117         * @since S60 3.2
       
  1118         * @param aSize New icon size.
       
  1119         * @return KErrNone if the operation succeeded, otherwise an error code.
       
  1120         */
       
  1121         IMPORT_C TInt SetIconSize( const TSize& aSize );
       
  1122 
       
  1123         /**
       
  1124         * Checks if the button uses default margins.
       
  1125         *
       
  1126         * @since S60 3.2
       
  1127         *
       
  1128         * @return ETrue if default margins are used.
       
  1129         */
       
  1130         TBool UsesDefaultMargins() const;  
       
  1131 
       
  1132         /**
       
  1133          * Sets tooltip to hide or show itself when background faded.
       
  1134          *
       
  1135          * @since S60 3.2
       
  1136          * @param aHide should be ETrue if hiding, EFalse if showing
       
  1137          */
       
  1138         void HideTooltipWhenAppFaded( TBool aHide ); 
       
  1139 
       
  1140 
       
  1141         /**
       
  1142          */
       
  1143         void CheckHitArea();
       
  1144         
       
  1145         /**
       
  1146          * Resets button to unpressed state.
       
  1147          *
       
  1148          * @since S60 5.0
       
  1149          */
       
  1150         IMPORT_C void ResetState();
       
  1151         
       
  1152         /**
       
  1153         * Sets button to use additional masks during drawing. Calling this
       
  1154         * method forces button to bypass the normal drawing routine i.e. 
       
  1155         * method DrawMaskedL is executed instead of Draw.
       
  1156         *
       
  1157         * @since S60 5.0
       
  1158         * @param aMaskedDraw ETrue to use additional mask.
       
  1159         */
       
  1160         void UseMaskedDraw( TBool aMaskedDraw );
       
  1161 
       
  1162         /**
       
  1163         * Registers resource provider.
       
  1164         * @param aProvider New resource provider.
       
  1165         */
       
  1166         void RegisterResourceProvider( CAknResourceProvider* aProvider );
       
  1167 
       
  1168         /**
       
  1169         * Unregisters resource provider.
       
  1170         */
       
  1171         void UnregisterResourceProvider();
       
  1172         
       
  1173         CAknsFrameBackgroundControlContext* BgContext();
       
  1174         
       
  1175         /**
       
  1176         * Removes the currently active state from the button,
       
  1177         * and sets the current state to the previous one.
       
  1178         */
       
  1179         void RemoveCurrentState();
       
  1180 
       
  1181         /**
       
  1182         * Returns the button touchable area.
       
  1183         *
       
  1184         * @since S60 5.0
       
  1185         * @return Button touch area
       
  1186         */
       
  1187         TRect TouchArea() const;
       
  1188 
       
  1189         /**
       
  1190         * Enables or disables tactile feedback for button. By default it is 
       
  1191         * enabled. Should be used to temporarily prevent updating of tactile 
       
  1192         * feedback area for performance reasons when button is moved 
       
  1193         * constantly.
       
  1194         *
       
  1195         * @param aEnable, ETrue to enable, EFalse to disable 
       
  1196         * @since S60 5.2
       
  1197         */
       
  1198         IMPORT_C void EnableFeedback( TBool aEnable ); 
       
  1199 
       
  1200     protected: // Constructors
       
  1201 
       
  1202         /**
       
  1203          * C++ constructor for the one state button.
       
  1204          *
       
  1205          * @param aFlags The flags for the button
       
  1206          */
       
  1207         IMPORT_C CAknButton( const TInt aFlags );
       
  1208 
       
  1209         /**
       
  1210          * Symbian 2nd phase constructor.
       
  1211          */
       
  1212         IMPORT_C void ConstructL();
       
  1213 
       
  1214         /**
       
  1215          * Symbian 2nd phase constructor.
       
  1216          *
       
  1217          * @param aIcon The icon for the normal state. Takes ownership.
       
  1218          * @param aDimmedIcon The icon for the dimmed state. Takes ownership.
       
  1219          * @param aPressedIcon The icon for the pressed down. Takes ownership.
       
  1220          * @param aHoverIcon The icon for the hover state.
       
  1221          * @param aText The text inside the button.
       
  1222          * @param aHelpText The text for the tooltip.
       
  1223          * @param aStateFlags The flags for the first state.
       
  1224          */
       
  1225         IMPORT_C void ConstructL( CGulIcon* aIcon, 
       
  1226                                   CGulIcon* aDimmedIcon, 
       
  1227                                   CGulIcon* aPressedIcon,
       
  1228                                   CGulIcon* aHoverIcon,
       
  1229                                   const TDesC& aText, 
       
  1230                                   const TDesC& aHelpText, 
       
  1231                                   const TInt aStateFlags );
       
  1232 
       
  1233         /**
       
  1234          * Symbian 2nd phase constructor.
       
  1235          *
       
  1236          * @param aFilePath The path to the file which contains icons.
       
  1237          * @param aBmpId The bitmap ID for the normal state icon.
       
  1238          * @param aMaskId The mask ID for the normal state icon.
       
  1239          * @param aDimmedBmpId The bitmap ID for the dimmed state icon.
       
  1240          * @param aDimmedMaskId The mask ID for the dimmed state icon.
       
  1241          * @param aPressedBmpId The bitmap ID for the pressed down state.
       
  1242          * @param aPressedMaskId The mask ID for the pressed down state.
       
  1243          * @param aHoverBmpId The bitmap ID for the hover state icon.
       
  1244          * @param aHoverMaskId The mask ID for the hover state icon.
       
  1245          * @param aText The text inside the button.
       
  1246          * @param aHelpText The text for the tooltip.
       
  1247          * @param aStateFlags The flags for the first state.
       
  1248          * @param aId Item ID of the masked bitmap to be created for skin 
       
  1249          *      specific icon.
       
  1250          * @param aDimmedId Item ID of the dimmed masked bitmap to be created 
       
  1251          *      for skin specific icon.
       
  1252          * @param aPressedId Item ID of the pressed masked bitmap to be created 
       
  1253          *      for skin specific icon.
       
  1254          * @param aHoverId Item ID of the masked hover bitmap to be created
       
  1255          *      for skin specific icon.
       
  1256          */
       
  1257         IMPORT_C void ConstructL( const TDesC& aFilePath, 
       
  1258                                   const TInt aBmpId, 
       
  1259                                   const TInt aMaskId,
       
  1260                                   const TInt aDimmedBmpId, 
       
  1261                                   const TInt aDimmedMaskId,
       
  1262                                   const TInt aPressedBmpId, 
       
  1263                                   const TInt aPressedMaskId, 
       
  1264                                   const TInt aHoverBmpId,
       
  1265                                   const TInt aHoverMaskId,
       
  1266                                   const TDesC& aText, 
       
  1267                                   const TDesC& aHelpText, 
       
  1268                                   const TInt aStateFlags,
       
  1269                                   const TAknsItemID& aId = KAknsIIDNone, 
       
  1270                                   const TAknsItemID& aDimmedId = KAknsIIDNone, 
       
  1271                                   const TAknsItemID& aPressedId = KAknsIIDNone,
       
  1272                                   const TAknsItemID& aHoverId = KAknsIIDNone );
       
  1273 
       
  1274     protected: // Functions from base class
       
  1275 
       
  1276         /**
       
  1277          * Responds to size changes to sets the size and position of the 
       
  1278          * contents of this control.
       
  1279          */
       
  1280         IMPORT_C void SizeChanged();
       
  1281 
       
  1282         /**
       
  1283          * This function is called whenever a control gains or loses focus.
       
  1284          *
       
  1285          * @param aDrawNow Contains the value that was passed to it by SetFocus().
       
  1286          */
       
  1287         IMPORT_C void FocusChanged( TDrawNow aDrawNow );
       
  1288 
       
  1289         /**
       
  1290          * For future extensions
       
  1291          * 
       
  1292          * @param aInterface The ID for the extension interface.
       
  1293          */
       
  1294         IMPORT_C void* ExtensionInterface( TUid aInterface );
       
  1295 
       
  1296     protected: // New functions
       
  1297 
       
  1298         /**
       
  1299          * Changes the state of the button to the next one.
       
  1300          *
       
  1301          * @return the current state index
       
  1302          */
       
  1303         IMPORT_C TInt ChangeState( TBool aDrawNow );
       
  1304 
       
  1305         /**
       
  1306          * Returns the text, which will be displayed inside the button 
       
  1307          * for the current state.
       
  1308          */
       
  1309         IMPORT_C const TDesC&  GetCurrentText() const;
       
  1310 
       
  1311         /**
       
  1312          * Returns icon for the current state.
       
  1313          */
       
  1314         IMPORT_C const CGulIcon* GetCurrentIcon() const;
       
  1315 
       
  1316         /**
       
  1317          * Shows help text for a certain period of time.
       
  1318          */
       
  1319         IMPORT_C void ShowHelpL();
       
  1320 
       
  1321         /**
       
  1322          * Hides help text after certain interval.
       
  1323          */
       
  1324         IMPORT_C void HideHelp();
       
  1325 
       
  1326 
       
  1327    private: // Functions from base class
       
  1328 
       
  1329         /**
       
  1330          * From CCoeControl. Draws the control. Called by window server.
       
  1331          */
       
  1332         IMPORT_C void Draw( const TRect& aRect ) const;  
       
  1333 
       
  1334     private: // New functions
       
  1335 
       
  1336         /**
       
  1337          * Continues drawing of the button which has only text.
       
  1338          */
       
  1339         void DrawTextButton( CWindowGc& aGc ) const;
       
  1340 
       
  1341         /**
       
  1342          * Continues drawing of the button which has text. Called from 
       
  1343          * DrawTextButton and DrawTextAndIconButton
       
  1344          */
       
  1345         void DrawText( CWindowGc& aGc, TRect& aTextRect ) const;
       
  1346 
       
  1347         /**
       
  1348          * Continues drawing of the button which has only an icon in it.
       
  1349          */
       
  1350         void DrawIconButton( CWindowGc& aGc ) const;
       
  1351 
       
  1352         /**
       
  1353          * Continues drawing of the button which has both text and icon.
       
  1354          */
       
  1355         void DrawTextAndIconButton( CWindowGc& aGc ) const;
       
  1356         
       
  1357         /**
       
  1358          * Starts the long press timer.
       
  1359          */
       
  1360         void StartLongPressTimerL();
       
  1361 
       
  1362         /**
       
  1363          * Stops the long press timer.
       
  1364          */
       
  1365         void StopLongPressTimer();
       
  1366 
       
  1367         /**
       
  1368          * Starts the timer for the key repeat.
       
  1369          */
       
  1370         void StartKeyRepeatTimerL();
       
  1371 
       
  1372         /**
       
  1373          * Stops the key repeat timer.
       
  1374          */
       
  1375         void StopKeyRepeatTimer();
       
  1376 
       
  1377         /**
       
  1378          * Called after timeout is over.
       
  1379          */
       
  1380         static TInt ReportKeyRepeatL( TAny* aThis );
       
  1381 
       
  1382         /**
       
  1383          * Asserts that extension class object exists.
       
  1384          *
       
  1385          * @return Extension object.
       
  1386          */
       
  1387         CAknButtonExtension* Extension() const;
       
  1388 
       
  1389         /**
       
  1390          * Updates tooltip position.
       
  1391          */
       
  1392         void UpdateTooltipPosition();
       
  1393 
       
  1394         /**
       
  1395          * Checks whether toolbar should send an EEventRequestExit event to
       
  1396          * command observe on button up event.
       
  1397          *
       
  1398          * @return ETrue if event should be sent, EFalse otherwise.
       
  1399          */
       
  1400         TBool RequestExit() const;
       
  1401 
       
  1402         /**
       
  1403          * Gets the rectangele reserved for button content excluding frame.
       
  1404          *
       
  1405          * @return Content rectangle.
       
  1406          */
       
  1407         TRect ContentRect() const;
       
  1408 
       
  1409         /**
       
  1410          * Checks whether button needs redrawing when it is pressed or released.
       
  1411          *
       
  1412          * @return ETrue, if redraw is needed, othewise EFalse.
       
  1413          */
       
  1414         TBool NeedsRedrawWhenPressed() const;
       
  1415 
       
  1416         /**
       
  1417          * Returns the ID of specified skin item.
       
  1418          */
       
  1419         TAknsItemID SkinIID( const TInt aIndex ) const;
       
  1420         
       
  1421         /**
       
  1422         * Calculates default margins.
       
  1423         */
       
  1424         void CalculateDefaultMargins();
       
  1425         
       
  1426         /**
       
  1427         * Scales all icons.
       
  1428         *
       
  1429         * @return KErrNone or an error code.
       
  1430         */
       
  1431         TInt ScaleIcons();
       
  1432         
       
  1433         /**
       
  1434         * Gets the correct text color.
       
  1435         *
       
  1436         * @return Text color.
       
  1437         */
       
  1438         TRgb TextColor() const;
       
  1439 
       
  1440         /**
       
  1441         * Generates the pressed down bitmaps
       
  1442         * if flag KAknButtonPressedDownFrame is set and button has no frame
       
  1443         */
       
  1444         void CreatePressedDownFrameL();
       
  1445         
       
  1446         /**
       
  1447          * Calculates color's luminance. 
       
  1448          */
       
  1449         TInt CalculateLuminance( const TRgb& aColor ) const; 
       
  1450 
       
  1451         /**
       
  1452          * Converts outline color, if fill color is too similar to outline color
       
  1453          * 
       
  1454          * @aFillColor fill color
       
  1455          * @aOutlineColor outline color
       
  1456          */
       
  1457         void ConvertColorsForOutlineEffect( TRgb& aFillColor, TRgb& aOutlineColor ) const; 
       
  1458 
       
  1459         /**
       
  1460          * Gets text colors 
       
  1461          * 
       
  1462          * @aPenColor pen color
       
  1463          * @aBrushColor brush color 
       
  1464          */
       
  1465         void GetTextColors( TRgb& aPenColor, TRgb& aBrushColor ) const; 
       
  1466         
       
  1467         /**
       
  1468          * Sets new state index 
       
  1469          * 
       
  1470          * @param aNewIndex New state index
       
  1471          */
       
  1472         void SetStateIndexL( TInt aNewIndex );
       
  1473         
       
  1474         /**
       
  1475          * Sets frame IDs for background context. This is called when there
       
  1476          * are possible changes in frame ids. 
       
  1477          */
       
  1478         void SetFrameIDs() const; 
       
  1479 
       
  1480         /**
       
  1481          * Sets frame rects for background context. This is called when
       
  1482          * button's size changes 
       
  1483          */
       
  1484         void SetFrameRects(); 
       
  1485 
       
  1486         /**
       
  1487          * Converts text to visual and clips it. This is called when there
       
  1488          * are possible changes in visual text or text area changed.
       
  1489          * Notice that if the text area size is changed, clipped visual text 
       
  1490          * should be regenerated. 
       
  1491          *
       
  1492          * @param aRect new text area.         
       
  1493          *         
       
  1494          */
       
  1495         void ConvertTextToVisualAndClip( const TRect& aRect ) const; 
       
  1496         
       
  1497         /*
       
  1498          * Get rect for icon and text of the current button state .
       
  1499          * 
       
  1500          * @param aIconRect the rectangle for icon. If no icon used in current state,
       
  1501          *                 this will be EUninitialized.
       
  1502          * @param aTextRect the rectangle for text. If no text in current state,
       
  1503          *                 this will be EUninitialized.
       
  1504          */
       
  1505         void GetCurrentStateTextAndIconRect( TRect& aIconRect, TRect& aTextRect ) const;
       
  1506 
       
  1507     protected: // Data
       
  1508 
       
  1509         // array to keep states
       
  1510         CArrayPtrFlat<CAknButtonState>* iStates;
       
  1511 
       
  1512         // button flags
       
  1513         TInt iFlags;
       
  1514 
       
  1515         // current button state index
       
  1516         TInt iStateIndex;
       
  1517 
       
  1518         // flag to define whether the button is pressed
       
  1519         TBool iButtonPressed;
       
  1520 
       
  1521         // number of drag events, needed to distinguish when it is outside 
       
  1522         // the button.
       
  1523         TInt iNumberOfDragEvents; 
       
  1524 
       
  1525         // Flag which shows whether key down event was reported before key up 
       
  1526         // event was sent to the button, because some controls consume key down 
       
  1527         // but don't consume key up events which might cause of button state 
       
  1528         // when it is not expected
       
  1529         TBool iKeyDownReported;
       
  1530 
       
  1531         // Background control context for button's frame
       
  1532         CAknsFrameBackgroundControlContext* iBgContext;
       
  1533 
       
  1534         // Customized highlight rectangular around the button if the default one
       
  1535         // won't be used
       
  1536         TRect iHighlightRect;
       
  1537 
       
  1538         // text button specific data  
       
  1539         const CFont*                    iFont;                // font for the text inside the button
       
  1540         TAlignment                      iVerticalAlignment;   // vertical alignment for the text. Centered by default
       
  1541         CGraphicsContext::TTextAlign    iHorizontalAlignment; // horizontal alignment for the text. Centered by default
       
  1542         TAknsItemID                     iTextColorTableId;    // id for the color table 
       
  1543         TInt                            iTextColorIndex;      // index of the color in color table
       
  1544 
       
  1545         // icon button specific data
       
  1546         TScaleMode  iScaleMode; // scale mode for the icon, by default it is EAspectRatioNotPreserved
       
  1547 
       
  1548         // tooltip specific data
       
  1549         TInt        iHelpNoteWaitInterval;         // interval in milliseconds between the time when the button got focused and the help text is shown
       
  1550         TInt        iHelpNoteInViewInterval;       // interval during which help text is shown in milliseconds
       
  1551         CAknInfoPopupNoteController* iHelpNote;    // component to show help text
       
  1552         HBufC*      iDimmedHelpText;               // help text in case if the button is dimmed, not used currently
       
  1553         TBool       iShowHelp;                     // flag which specifies whether help note should be shown 
       
  1554 
       
  1555         // Key repeat handling
       
  1556         CPeriodic* iKeyRepeatTimer; // timer to report key repeats
       
  1557         TInt iKeyRepeatDelay;       // initial delay for key repeats
       
  1558         TInt iKeyRepeatInterval;    // time interval for key repeats
       
  1559     
       
  1560     private:
       
  1561         CAknButtonExtension* iExtension;
       
  1562 
       
  1563     };
       
  1564 
       
  1565 
       
  1566 #endif // __AKNBUTTON_H__
       
  1567 
       
  1568 // End of File