AknButton.h

00001 /*
00002 * ============================================================================
00003 *  Name        : AknButton.h
00004 *  Part of     : UI Framework Core / EIKON Concrete Controls
00005 *  Description : Button component.
00006 *  Version     : %version: e003sa01#35.1.2 %
00007 *
00008 *  Copyright © 2005-2008 Nokia.  All rights reserved.
00009 *  This material, including documentation and any related computer
00010 *  programs, is protected by copyright controlled by Nokia.  All
00011 *  rights are reserved.  Copying, including reproducing, storing,
00012 *  adapting or translating, any or all of this material requires the
00013 *  prior written consent of Nokia.  This material also contains
00014 *  confidential information which may not be disclosed to others
00015 *  without the prior written consent of Nokia.
00016 * ============================================================================
00017 */
00020 #ifndef __AKNBUTTON_H__
00021 #define __AKNBUTTON_H__
00022 
00023 //  INCLUDES
00024 #include <akncontrol.h>
00025 #include <akniconutils.h>
00026 #include <aknutils.h>
00028 // FORWARD DECLARATIONS
00029 class CGulIcon;
00030 class CAknButton;
00031 class CAknButtonExtension; 
00032 class CAknInfoPopupNoteController;
00033 class CAknButtonStateExtension;
00034 class CAknPictographInterface;
00035 class CAknsFrameBackgroundControlContext;
00036 class CAknResourceProvider;
00038 // CLASS DECLARATION
00046 class CAknButtonState : public CBase
00047     {           
00048     public: // Constructors and destructors
00053         IMPORT_C ~CAknButtonState();
00055     protected: // Constructors and destructors
00062         IMPORT_C CAknButtonState( const TInt aFlags );
00074         IMPORT_C void ConstructL( CGulIcon* aIcon,
00075                                   CGulIcon* aDimmedIcon, 
00076                                   CGulIcon* aPressedIcon,
00077                                   CGulIcon* aHoverIcon,
00078                                   const TDesC& aText, 
00079                                   const TDesC& aHelpText );
00104         IMPORT_C void ConstructL( const TDesC& aFilePath, 
00105                                   const TInt aBmpId, 
00106                                   const TInt aMaskId,
00107                                   const TInt aDimmedBmpId, 
00108                                   const TInt aDimmedMaskId,
00109                                   const TInt aPressedBmpId, 
00110                                   const TInt aPressedMaskId,
00111                                   const TInt aHoverBmpId,
00112                                   const TInt aHoverMaskId,
00113                                   const TDesC& aText, 
00114                                   const TDesC& aHelpText,
00115                                   const TAknsItemID& aId = KAknsIIDNone, 
00116                                   const TAknsItemID& aDimmedId = KAknsIIDNone, 
00117                                   const TAknsItemID& aPressedId = KAknsIIDNone,
00118                                   const TAknsItemID& aHoverId = KAknsIIDNone );
00120     public: // New functions
00127         IMPORT_C const CGulIcon* Icon() const;
00134         IMPORT_C const CGulIcon* DimmedIcon() const;
00141         IMPORT_C const CGulIcon* PressedIcon() const;
00148         IMPORT_C const CGulIcon* HoverIcon() const;
00155         IMPORT_C const TDesC& Text() const;
00162         IMPORT_C const TDesC& HelpText() const;
00169         IMPORT_C TInt Flags() const;
00176         IMPORT_C void SetIcon( CGulIcon* aIcon );
00183         IMPORT_C void SetDimmedIcon( CGulIcon* aDimmedIcon );
00190         IMPORT_C void SetPressedIcon( CGulIcon* aPressedIcon );
00197         IMPORT_C void SetHoverIcon( CGulIcon* aHoverIcon );
00204         IMPORT_C void SetTextL( const TDesC& aText );
00211         IMPORT_C void SetHelpTextL( const TDesC& aHelpText );
00218         IMPORT_C void SetFlags( const TInt aFlags );
00225         void UpdateIconL( const TDesC& aFilePath, 
00226                           const TInt aBmpId, 
00227                           const TInt aMaskId,
00228                           const TInt aDimmedBmpId, 
00229                           const TInt aDimmedMaskId,
00230                           const TInt aPressedBmpId, 
00231                           const TInt aPressedMaskId,
00232                           const TInt aHoverBmpId,
00233                           const TInt aHoverMaskId,
00234                           const TAknsItemID& aId = KAknsIIDNone, 
00235                           const TAknsItemID& aDimmedId = KAknsIIDNone, 
00236                           const TAknsItemID& aPressedId = KAknsIIDNone,
00237                           const TAknsItemID& aHoverId = KAknsIIDNone );
00241     protected: // New functions
00248         IMPORT_C virtual void ConstructFromResourceL( TResourceReader& aReader );
00257         IMPORT_C virtual void SizeChanged( const TRect& aRect, 
TScaleMode aScaleMode );
00263         IMPORT_C TBool HasText() const;
00269         IMPORT_C TBool HasHelp() const;
00277         void HandleResourceChange( TInt aType );
00285         void SetIconScaleMode( const TScaleMode aScaleMode );
00287     private: // new functions
00300         void CreateButtonIconL( CGulIcon*& aIcon, const TDesC& aFilePath, 
00301                                 TInt aBmpId, TInt aMaskId, 
00302                                 const TAknsItemID& aId = KAknsIIDNone ) const;
00317         void LoadButtonIcon( CGulIcon*& aIcon ) const;
00325         void ReplaceIcon( CGulIcon*& aIcon, CGulIcon* aNewIcon );
00335         TInt ScaleIcons( const TSize& aSize, TScaleMode aScaleMode );
00340         CAknButtonStateExtension* Extension() const;
TScaleMode ScaleMode() const;
00351         void SetGeneratedDimmedIcon( TBool aDimmedIconCreatedByButton );
00353         friend class CAknButton;
00355     protected: // data
00356         CGulIcon*   iIcon;                      // bitmaps for normal state
00357         CGulIcon*   iDimmedIcon;                // bitmaps for dimmed icon
00358         CGulIcon*   iPressedIcon;               // bitmaps for pressed but not activated state
00359         CGulIcon*   iHoverIcon;                 // bitmaps for hover icon
00360         HBufC*      iText;                      // text for normal state
00361         HBufC*      iHelpText;                  // text which is shown as a help
00362         TInt        iFlags;                     // flags for the state
00363         CAknButtonStateExtension* iExtension;   // for future extensions
00364     };
00367 // CLASS DECLARATION
00375 class CAknButton : public CAknControl
00376     {
00377     public: // Enumerations
00379         enum TAlignment
00380             {
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 */
00386             };
00388         enum TTooltipPosition
00389             {
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 */
00394             };
00396         enum TTextAndIconAlignment
00397             {
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 */
00403             };            
00405         enum TButtonEvent
00406             {
ELongPressEvent = 100, /* Observer event for long press event */
ELongPressEndedEvent   /* Observer event for long press ended event */
00409             };
00411     public: // Constructors and destructors
00417         IMPORT_C static CAknButton* NewL();
00422         IMPORT_C static CAknButton* NewLC();
00430         IMPORT_C static CAknButton* NewL( TResourceReader& aReader );
00438         IMPORT_C static CAknButton* NewLC( TResourceReader& aReader ); 
00445         IMPORT_C static CAknButton* NewL( const TInt aResourceId );
00452         IMPORT_C static CAknButton* NewLC( const TInt aResourceId );
00466         IMPORT_C static CAknButton* NewL( CGulIcon* aIcon, 
00467                                           CGulIcon* aDimmedIcon,
00468                                           CGulIcon* aPressedIcon,
00469                                           CGulIcon* aHoverIcon,
00470                                           const TDesC& aText, 
00471                                           const TDesC& aHelpText, 
00472                                           const TInt aButtonFlags,
00473                                           const TInt aStateFlags );
00487         IMPORT_C static CAknButton* NewLC( CGulIcon* aIcon, 
00488                                            CGulIcon* aDimmedIcon,
00489                                            CGulIcon* aPressedIcon,
00490                                            CGulIcon* aHoverIcon,
00491                                            const TDesC& aText, 
00492                                            const TDesC& aHelpText, 
00493                                            const TInt aFlags,
00494                                            const TInt aStateFlags );
00521         IMPORT_C static CAknButton* NewL( const TDesC& aFilePath, 
00522                                           const TInt aBmpId, 
00523                                           const TInt aMaskId,
00524                                           const TInt aDimmedBmpId, 
00525                                           const TInt aDimmedMaskId,
00526                                           const TInt aPressedBmpId, 
00527                                           const TInt aPressedMaskId,
00528                                           const TInt aHoverBmpId,
00529                                           const TInt aHoverMaskId,
00530                                           const TDesC& aText, 
00531                                           const TDesC& aHelpText, 
00532                                           const TInt aButtonFlags, 
00533                                           const TInt aStateFlags,
00534                                           const TAknsItemID& aId = KAknsIIDNone, 
00535                                           const TAknsItemID& aDimmedId = KAknsIIDNone, 
00536                                           const TAknsItemID& aPressedId = KAknsIIDNone,
00537                                           const TAknsItemID& aHoverId = KAknsIIDNone );
00564         IMPORT_C static CAknButton* NewLC( const TDesC& aFilePath, 
00565                                            const TInt aBmpId, 
00566                                            const TInt aMaskId,
00567                                            const TInt aDimmedBmpId, 
00568                                            const TInt aDimmedMaskId,
00569                                            const TInt aPressedBmpId, 
00570                                            const TInt aPressedMaskId, 
00571                                            const TInt aHoverBmpId,
00572                                            const TInt aHoverMaskId,
00573                                            const TDesC& aText, 
00574                                            const TDesC& aHelpText, 
00575                                            const TInt aButtonFlags, 
00576                                            const TInt aStateFlags,
00577                                            const TAknsItemID& aId = KAknsIIDNone, 
00578                                            const TAknsItemID& aDimmedId = KAknsIIDNone, 
00579                                            const TAknsItemID& aPressedId = KAknsIIDNone,
00580                                            const TAknsItemID& aHoverId = KAknsIIDNone );
00585         IMPORT_C virtual ~CAknButton();
00587     public: // Functions from base class
00592         IMPORT_C void ActivateL();
00600         IMPORT_C void ConstructFromResourceL( TResourceReader& aReader );
00607         IMPORT_C void HandleResourceChange( TInt aType );
00617         IMPORT_C TSize MinimumSize();
00628         IMPORT_C void SetDimmed( TBool aDimmed );
00637         IMPORT_C TKeyResponse OfferKeyEventL( const TKeyEvent& aKeyEvent, 
00638                                               TEventCode aType );
00646         IMPORT_C void MakeVisible( TBool aVisible );
00653         IMPORT_C void PrepareForFocusLossL();
00660         IMPORT_C void PrepareForFocusGainL(); 
00667         IMPORT_C void HandlePointerEventL( const TPointerEvent& aPointerEvent );
00672         IMPORT_C virtual void PositionChanged();  
00674     public: // New functions
00681         IMPORT_C void ConstructFromResourceL( const TInt aResourceId );
00689         IMPORT_C virtual void SetCurrentState( const TInt aStateIndex, 
00690                                                const TBool aDrawNow );
00707         IMPORT_C virtual void AddStateL( CGulIcon* aIcon, 
00708                                          CGulIcon* aDimmedIcon, 
00709                                          CGulIcon* aPressedIcon,
00710                                          CGulIcon* aHoverIcon,
00711                                          const TDesC& aText, 
00712                                          const TDesC& aHelpText, 
00713                                          const TInt aStateFlags );
00741         IMPORT_C virtual void AddStateL( const TDesC& aFilePath, 
00742                                          const TInt aBmpId, 
00743                                          const TInt aMaskId,
00744                                          const TInt aDimmedBmpId, 
00745                                          const TInt aDimmedMaskId,
00746                                          const TInt aPressedBmpId, 
00747                                          const TInt aPressedMaskId, 
00748                                          const TInt aHoverBmpId,
00749                                          const TInt aHoverMaskId,
00750                                          const TDesC& aText,
00751                                          const TDesC& aHelpText,
00752                                          const TInt aStateFlags,
00753                                          const TAknsItemID& aId, 
00754                                          const TAknsItemID& aDimmedId, 
00755                                          const TAknsItemID& aPressedId,
00756                                          const TAknsItemID& aHoverId );
00776         void AddStateL( CGulIcon* aIcon, 
00777                         CGulIcon* aDimmedIcon, 
00778                         CGulIcon* aPressedIcon,
00779                         CGulIcon* aHoverIcon,
00780                         const TDesC& aText, 
00781                         const TDesC& aHelpText, 
00782                         const TInt aStateFlags,
00783                         const TInt aCommandId );
00793         IMPORT_C void SetButtonFlags( const TInt aFlags );
00820         IMPORT_C void SetFrameAndCenterIds( const TAknsItemID& aFrameId, 
00821                                             const TAknsItemID& aCenterId,
00822                                             const TAknsItemID& aLatchedFrameId, 
00823                                             const TAknsItemID& aLatchedCenterId,
00824                                             const TAknsItemID& aDimmedFrameId, 
00825                                             const TAknsItemID& aDimmedCenterId,
00826                                             const TAknsItemID& aPressedFrameId, 
00827                                             const TAknsItemID& aPressedCenterId,
00828                                             const TAknsItemID& aLatchedDimmedFrameId, 
00829                                             const TAknsItemID& aLatchedDimmedCenterId );
00851         IMPORT_C void SetBackgroundIds( const TAknsItemID& aBackgroundId, 
00852                                         const TAknsItemID& aLatchedBackgroundId, 
00853                                         const TAknsItemID& aDimmedBackgroundId, 
00854                                         const TAknsItemID& aPressedBackgroundId, 
00855                                         const TAknsItemID& aLatchedDimmedBackgroundId );
00863         IMPORT_C void SetTextFont( const CFont* aFont );
00873         IMPORT_C void SetTextColorIds( const TAknsItemID& aTextColorTableId, 
00874                                        const TInt aTextColorIndex );
00883         IMPORT_C void SetTextHorizontalAlignment( 
00884             const CGraphicsContext::TTextAlign aHorizontalAlignment );
00893         IMPORT_C void SetTextVerticalAlignment( 
00894             const CAknButton::TAlignment aVerticalAlignment );
00901         IMPORT_C void SetTextAndIconAlignment( 
00902             const CAknButton::TTextAndIconAlignment aAlignment );
00910         IMPORT_C void SetTextUnderlineStyle( TFontUnderline aUnderlineStyle );
00918         IMPORT_C void SetIconScaleMode( const TScaleMode aScaleMode );
00926         IMPORT_C void SetIconHorizontalAlignment( 
00927             const CAknButton::TAlignment aHorizontalAlignment );
00935         IMPORT_C void SetIconVerticalAlignment( 
00936             const CAknButton::TAlignment aVerticalAlignment );
00947         IMPORT_C void SetHelpNoteTimeouts( const TInt aBeforeTimeout, 
00948                                            const TInt aInViewTimeout );
00958         IMPORT_C void SetKeyRepeatInterval( const TInt aKeyRepeatDelay, 
00959                                             const TInt aKeyRepeatInterval );
00971         IMPORT_C void SetLongPressInterval( const TInt aLongPressInterval );
00976         IMPORT_C TInt StateIndex() const;
00985         IMPORT_C void EnablePictographsL( CAknPictographInterface& aInterface );
00992         IMPORT_C void DisablePictographs();
01000         IMPORT_C void SetHighlightRect( const TRect& aRect );
01007         IMPORT_C TRect HighlightRect() const;
01014         IMPORT_C void SetTooltipPosition( const TTooltipPosition aPosition );
01022         IMPORT_C void SetRequestExit( const TBool aRequestExit );
01031         IMPORT_C TBool IsDimmed() const;
01038         IMPORT_C void SetDimmedHelpTextL( const TDesC& aHelpText );
01048         TBool HitAreaContainsL( const TPoint& aPoint, TBool aCheckHitArea ) const; 
01055         IMPORT_C CAknButtonState* State() const;
01063         IMPORT_C CAknButtonState* State( const TInt aStateIndex ) const;
01070         IMPORT_C TInt ButtonFlags() const;
01082         IMPORT_C void SetMargins( const TMargins8& aMargins );
01094         IMPORT_C TInt SetIconSize( const TSize& aSize );
01103         TBool UsesDefaultMargins() const;  
01111         void HideTooltipWhenAppFaded( TBool aHide ); 
01116         void CheckHitArea();
01123         IMPORT_C void ResetState();
01133         void UseMaskedDraw( TBool aMaskedDraw );
01139         void RegisterResourceProvider( CAknResourceProvider* aProvider );
01144         void UnregisterResourceProvider();
CAknsFrameBackgroundControlContext* BgContext();
01152         void RemoveCurrentState();
01160         TRect TouchArea() const;
01162     protected: // Constructors
01169         IMPORT_C CAknButton( const TInt aFlags );
01174         IMPORT_C void ConstructL();
01187         IMPORT_C void ConstructL( CGulIcon* aIcon, 
01188                                   CGulIcon* aDimmedIcon, 
01189                                   CGulIcon* aPressedIcon,
01190                                   CGulIcon* aHoverIcon,
01191                                   const TDesC& aText, 
01192                                   const TDesC& aHelpText, 
01193                                   const TInt aStateFlags );
01219         IMPORT_C void ConstructL( const TDesC& aFilePath, 
01220                                   const TInt aBmpId, 
01221                                   const TInt aMaskId,
01222                                   const TInt aDimmedBmpId, 
01223                                   const TInt aDimmedMaskId,
01224                                   const TInt aPressedBmpId, 
01225                                   const TInt aPressedMaskId, 
01226                                   const TInt aHoverBmpId,
01227                                   const TInt aHoverMaskId,
01228                                   const TDesC& aText, 
01229                                   const TDesC& aHelpText, 
01230                                   const TInt aStateFlags,
01231                                   const TAknsItemID& aId = KAknsIIDNone, 
01232                                   const TAknsItemID& aDimmedId = KAknsIIDNone, 
01233                                   const TAknsItemID& aPressedId = KAknsIIDNone,
01234                                   const TAknsItemID& aHoverId = KAknsIIDNone );
01236     protected: // Functions from base class
01242         IMPORT_C void SizeChanged();
01249         IMPORT_C void FocusChanged( TDrawNow aDrawNow );
01256         IMPORT_C void* ExtensionInterface( TUid aInterface );
01258     protected: // New functions
01265         IMPORT_C TInt ChangeState( TBool aDrawNow );
01271         IMPORT_C const TDesC&  GetCurrentText() const;
01276         IMPORT_C const CGulIcon* GetCurrentIcon() const;
01281         IMPORT_C void ShowHelpL();
01286         IMPORT_C void HideHelp();
01289    private: // Functions from base class
01294         IMPORT_C void Draw( const TRect& aRect ) const;  
01296     private: // New functions
01301         void DrawTextButton( CWindowGc& aGc ) const;
01306         void DrawIconButton( CWindowGc& aGc ) const;
01311         void DrawTextAndIconButton( CWindowGc& aGc ) const;
01316         void DrawMaskedL( CWindowGc& aGc ) const;
01321         void StartLongPressTimerL();
01326         void StopLongPressTimer();
01331         void StartKeyRepeatTimerL();
01336         void StopKeyRepeatTimer();
01341         static TInt ReportKeyRepeatL( TAny* aThis );
01348         CAknButtonExtension* Extension() const;
01353         void UpdateTooltipPosition();
01361         TBool RequestExit() const;
01368         TRect ContentRect() const;
01375         TBool NeedsRedrawWhenPressed() const;
TAknsItemID SkinIID( const TInt aIndex ) const;
01385         void CalculateDefaultMargins();
01392         TInt ScaleIcons();
01399         TRgb TextColor() const;
01405         void CreatePressedDownFrameL();
01410         TInt CalculateLuminance( const TRgb& aColor ) const; 
01418         void ConvertColorsForOutlineEffect( TRgb& aFillColor, TRgb& aOutlineColor ) const; 
01426         void GetTextColors( TRgb& aPenColor, TRgb& aBrushColor ) const; 
01433         void SetStateIndexL( TInt aNewIndex );
01435     protected: // Data
01437         // array to keep states
01438         CArrayPtrFlat<CAknButtonState>* iStates;
01440         // button flags
01441         TInt iFlags;
01443         // current button state index
01444         TInt iStateIndex;
01446         // flag to define whether the button is pressed
01447         TBool iButtonPressed;
01449         // number of drag events, needed to distinguish when it is outside 
01450         // the button.
01451         TInt iNumberOfDragEvents; 
01453         // Flag which shows whether key down event was reported before key up 
01454         // event was sent to the button, because some controls consume key down 
01455         // but don't consume key up events which might cause of button state 
01456         // when it is not expected
01457         TBool iKeyDownReported;
01459         // Background control context for button's frame
01460         CAknsFrameBackgroundControlContext* iBgContext;
01462         // Customized highlight rectangular around the button if the default one
01463         // won't be used
01464         TRect iHighlightRect;
01466         // text button specific data  
01467         const CFont*                    iFont;                // font for the text inside the button
01468         TAlignment                      iVerticalAlignment;   // vertical alignment for the text. Centered by default
01469         CGraphicsContext::TTextAlign    iHorizontalAlignment; // horizontal alignment for the text. Centered by default
01470         TAknsItemID                     iTextColorTableId;    // id for the color table 
01471         TInt                            iTextColorIndex;      // index of the color in color table
01473         // icon button specific data
01474         TScaleMode  iScaleMode; // scale mode for the icon, by default it is EAspectRatioNotPreserved
01476         // tooltip specific data
01477         TInt        iHelpNoteWaitInterval;         // interval in milliseconds between the time when the button got focused and the help text is shown
01478         TInt        iHelpNoteInViewInterval;       // interval during which help text is shown in milliseconds
01479         CAknInfoPopupNoteController* iHelpNote;    // component to show help text
01480         HBufC*      iDimmedHelpText;               // help text in case if the button is dimmed, not used currently
01481         TBool       iShowHelp;                     // flag which specifies whether help note should be shown 
01483         // Key repeat handling
01484         CPeriodic* iKeyRepeatTimer; // timer to report key repeats
01485         TInt iKeyRepeatDelay;       // initial delay for key repeats
01486         TInt iKeyRepeatInterval;    // time interval for key repeats
01488     private:
01489         CAknButtonExtension* iExtension;
01491     };
01494 #endif // __AKNBUTTON_H__
01495 
01496 // End of File