MCL/sf/mw/classicui: comparison uifw/AvKon/inc/AknTitlePaneLabel.h

equal deleted inserted replaced

--1:000000000000
+:2f259fa3e83a
+/*
+* Copyright (c) 2005-2007 Nokia Corporation and/or its subsidiary(-ies).
+* All rights reserved.
+* This component and the accompanying materials are made available
+* under the terms of "Eclipse Public License v1.0"
+* which accompanies this distribution, and is available
+* at the URL "http://www.eclipse.org/legal/epl-v10.html".
+*
+* Initial Contributors:
+* Nokia Corporation - initial contribution.
+*
+* Contributors:
+*
+* Description:  Title pane's label.
+*
+*/
+#ifndef C_AKNTITLEPANELABEL_H
+#define C_AKNTITLEPANELABEL_H
+// INCLUDES
+#include <eiklabel.h>
+#include <AknUtils.h>
+// FORWARD DECLARATIONS
+class TAknLayoutText;
+// CLASS DECLARATION
+/**
+* This class is the text label which is used in title pane to display
+* texts.
+*
+* @lib avkon.lib
+*/
+NONSHARABLE_CLASS( CAknTitlePaneLabel ) : public CEikLabel,
+public MCoeForegroundObserver
+{
+public:
+/**
+* Supported effects:
+*
+* EEffectNone: No effect is applied, drawing is done as in CEikLabel::Draw()
+*
+* EEffectFadeToLeft: Text is faded to left using alpha blending.
+*
+* EEffectFadeToRight: Text is faded to right using alpha blending.
+*
+* EEffectDefaultScroll: Default scrolling effect. Text is scrolled in the
+*                       text window and when end or beginning of the text
+*                       is visible the scrolling direction is reversed.
+*
+* EEffectDefaultScrollWithFade: Same as EEffectDefaultScroll but text is
+*                               faded from the scrolling area start and end.
+*
+* EEffectLoopScroll: Loop scrolling effect. Text is scrolled in the
+*                    text window and when whole text has been scrolled
+*                    it starts again from the other side.
+*
+* EEffectLoopScrollWithFade: Same as EEffectLoopScroll but text is faded
+*                            from the scrolling area start and end.
+*
+* EEffectFadeOut: Text is transformed gradually from opaque to transparent.
+*
+* EEffectFadeIn: Text is transformed gradually from transparent to opaque.
+*
+* EEffectScrollOnceWithFade: Text is scrolled once and during scrolling
+*                            text is faded a bit from both ends.
+*
+* EEffectPause: Does nothing but waits.
+*
+* EEffectToggleScrolledTextTruncation: Toggles wheter text is drawn
+*                                      as truncated or not.
+*
+*/
+enum TAknTitlePaneLabelEffect
+{
+EEffectNone = 0,
+EEffectFadeToLeft,
+EEffectFadeToRight,
+EEffectDefaultScroll,
+EEffectDefaultScrollWithFade,
+EEffectLoopScroll,
+EEffectLoopScrollWithFade,
+EEffectFadeOut,
+EEffectFadeIn,
+EEffectScrollOnceWithFade,
+EEffectPause,
+EEffectToggleScrolledTextTruncation
+};
+/**
+* Struct for holding effect related data.
+*/
+struct SAknTitleLableEffect
+{
+SAknTitleLableEffect() : iEffect( 0 ),
+iEffectDuration( 0 ),
+iEffectRect( 0, 0, 0, 0 ),
+iLabelRect( 0, 0, 0, 0 ),
+iTitleText( NULL ),
+iObserver( NULL )
+{};
+TInt                iEffect;
+TInt                iEffectDuration;
+TRect               iEffectRect;
+TRect               iLabelRect;
+TAknLayoutText      iTextLayout;
+TAknTextLineLayout  iTextLayoutLine;
+HBufC*              iTitleText; // not owned
+CCoeControl*        iObserver;  // not owned
+};
+/**
+* Constructor
+*/
+CAknTitlePaneLabel();
+/**
+* Destructor
+*/
+~CAknTitlePaneLabel();
+/**
+* Sets given effect active.
+*
+* @param  aEffect          The effect to be activated
+*                          (@see TAknTitlePaneLabelEffect).
+* @param  aEffectRect      The rect where effect is to be activated.
+* @param  aEffectDuration  Duration of the effect.
+* @param  aTextLayout      TextLayout for title text.
+* @param  aTextLayoutLine  LayoutLine for title text.
+* @param  aTitleText       The text.
+*/
+void SetTextEffect( TInt aEffect,
+TRect aEffectRect,
+TInt aEffectDuration,
+TRect aLabelRect,
+TAknLayoutText aTextLayout,
+TAknTextLineLayout aTextLayoutLine,
+HBufC* aTitleText,
+CCoeControl* aObserver = NULL );
+/**
+* Returns currently active text effect id.
+* @return Currently active text effect id.
+*/
+TInt TextEffect();
+/**
+* Returns title text as bitmap if available. Otherwise NULL.
+* @return  Title text drawn to a bitmap.
+*          Ownership of bitmap is not transferred.
+*/
+	CFbsBitmap* TextAsBitmap();
+/**
+* Returns title text as mask bitmap if available. Otherwise NULL.
+* @return  Title text drawn to a bitmap.
+*          Ownership of bitmap is not transferred.
+*/
+	CFbsBitmap* TextAsMask();
+/**
+* Returns currently active text length in pixels.
+* @return Text lenght in pixels
+*/
+TInt TextLength();
+/**
+* Initializes and clears effect queue.
+*/
+	void InitEffectQueueL();
+/**
+* Adds given effect to queue.
+*
+* @param  aEffect  The effect to be added.
+*/
+	void AddToEffectQueueL( SAknTitleLableEffect aEffect );
+/**
+* Activates effect queue. All effects from queue are executed.
+*/
+	void ActivateEffectQueue();
+protected: // from @c CEikLabel
+/**
+* Actually draws the text to screen.
+*/
+void Draw( const TRect& aRect ) const;
+/**
+	 * Handles a change to the control's resources of type aType
+	 * which are shared across the environment, e.g. color scheme change.
+	 *
+	 * @param  aType  Event type.
+	 */
+void HandleResourceChange( TInt aType );
+public:
+/**
+* Enables Japanese pictograph support.
+*
+* @param  aInterface  Interface to be used in drawing the pictographs,
+*                     ownership is not transferred.
+*/
+void SetPictographInterface( CAknPictographInterface& aInterface );
+/**
+* Marks given text as invalid. It is no more used for drawing text.
+*/
+void InvalidateText();
+/**
+* Tells whether effect queue is empty.
+*
+* @return  @c ETrue if queue is empty, @c EFalse otherwise.
+*/
+	TBool EffectQueueIsEmpty();
+/**
+* Replaces control characters in the title text
+* with a space (0x20) character.
+*
+* @param[in,out] aText     Text which control characters are
+*                          to be replaced.
+*
+* @param aReplaceLinefeeds Determine if linefeeds (0x0A) and and paragraph
+*                          separatoirs (0x2029) are also converted just
+*                          like other control characters.
+*
+*/
+	void ReplaceControlCharacters( HBufC* aText, TBool aReplaceLinefeeds );
+private: // from @c MCoeForegroundObserver
+/**
+* Activates timer if needed.
+*/
+void HandleGainingForeground();
+/**
+* Cancels timer if active.
+*/
+void HandleLosingForeground();
+private:
+/**
+* Initializes effect, creates needed bitmap contextes etc.
+*/
+void InitEffectL();
+/**
+* Initializes timer for e.g. scrolling effect
+*
+* @param  aDelay    Initial delay before the first timer event
+*                   in microseconds.
+* @param  aInterval Interval between the consequent events
+*                   in microseconds.
+*/
+void InitTimerL( TInt aDelay, TInt aInterval );
+/**
+* Cancels timer for e.g. scrolling effect
+*/
+void CancelTimer();
+/**
+* Clears and initalizes bitmaps that are used for drawing the text.
+*/
+void InitBitmaps() const;
+/**
+* Draws the text without the truncation character (@c KEllipsis).
+* This is used with long texts that are scrolled, so that the
+* text is not truncated before the scrolling starts, but is
+* afterwards.
+* This function calls @c CEikLabel::Draw().
+*
+* @param  aRect  Passed to @c CEikLabel::Draw().
+*/
+void DrawWithoutTruncationL( const TRect& aRect );
+/**
+* Main function for drawing with effects. This method selects the proper
+* subroutine based on active effect. This function is intended to be used
+* instead of @c CEikLabel::Draw() functionality.
+*
+* If no effect is currently specified, this will call @c CEikLabel::Draw().
+*
+* @param  aRect  Passed to @c CEikLabel::Draw() if no effect is
+*                active.
+*/
+void DrawWithEffect( const TRect& aRect ) const;
+/**
+* Draws the text into bitmap context using selected effect.
+*/
+	void DrawTextWithEffect() const;
+/**
+* Draws the text into bitmap context using fade effect. Text is
+* faded by using alphablending.
+*/
+	void DrawTextWithFadeEffect() const;
+/**
+* Draws the text into bitmap context using scroll effect. Text is
+* scrolled one pixels every time timer expires.
+*/
+	void DrawTextWithScrollEffect() const;
+/**
+* Draws the text into bitmap context using scroll effect. Text is
+* scrolled one pixels every time timer expires. Additionally text is
+* faded from both sides to give scrolling a smoother look.
+*/
+	void DrawTextWithScrollAndFadeEffect() const;
+/**
+* Static funtion which is called when timer expires.
+*/
+static TInt EffectEvent( TAny* aPtr );
+/**
+* Funtion which is called when timer expires.
+*/
+void DoEffectEvent();
+/**
+* Funtions which manipulate text when timer event happens.
+*/
+TBool DoDefaultScrollEffectEvent();
+TBool DoLoopScrollEffectEvent();
+TBool DoScrollOnceEffectEvent();
+TBool DoFadeInEffectEvent();
+TBool DoFadeOutEffectEvent();
+TBool DoPauseEffectEvent();
+TBool DoToggleScrolledTextTruncationEffectEvent();
+/**
+* Test wheter text fits to screen at once.
+*
+* @return  @c ETrue  if truncation is needed,
+*          @c EFalse otherwise.
+*/
+	TBool TextNeedsTruncation() const;
+/**
+* Test wheter selected effect requires timed events.
+*
+* @param  aEffect  Effect to be checked
+*                  (@see TAknTitlePaneLabelEffect).
+*
+* @return @c ETrue  if timed events are needed,
+*         @c EFalse otherwise.
+*/
+	TBool EffectEventsNeeded( TInt aEffect ) const;
+/**
+* Test wheter selected effect requires bitmap devices.
+*
+* @param  aEffect  Effect to be checked
+*                  (@see TAknTitlePaneLabelEffect).
+*
+* @return @c ETrue  if bitmap devices are needed,
+*         @c EFalse otherwise.
+*/
+	TBool EffectBitmapsNeeded( TInt aEffect ) const;
+/**
+* Calculates suitable step for scrolling text.
+*
+* @return  Step size in pixels
+*/
+TInt ScrollStepInPixels() const;
+/**
+* Sets next effect from queue active.
+*/
+void NextEffect();
+/**
+* Creates scrolling text from given text.
+*
+* @param[in] aOriginalText The text from which the scrolling text
+*                          will be created from
+*/
+void CreateScrollingTextL( const HBufC* aOriginalText );
+private: // Member variables
+/** Currently active effect */
+TInt  iEffect;
+/** Previously active effect */
+TInt  iPreviousEffect;
+/** Area where currently active effect is applied */
+TRect iEffectRect;
+/** Area where scrolling is applied */
+TRect iScrollRect;
+/** Size of this control when effect was last time set active */
+TSize iEffectLabelSize;
+/** Timer for effects that require changes often (scroll) */
+CPeriodic* iEffectTimer;
+/** Duration of the effects */
+TInt  iEffectDuration;
+	/** Current position of scrolling text */
+	TInt  iScrollPosition;
+	/** Interval for scrolling text updates */
+	TInt  iScrollInterval;
+	/** Amount of pixels scrolling text is shifed each time that timer expires */
+	TInt  iScrollStep;
+	/** Determines the scrolling direction of the text */
+	TBool  iScrollDirectionBackwards;
+/** Alpha value for fade out text */
+TInt  iFadeInOutValue;
+/** Alpha value for fade in text */
+TInt  iFadeInOutStep;
+/** Phase where operator name effect is at the moment */
+TInt  iOperatorNamePhase;
+/** Title text, not owned */
+	HBufC* iTitleText;
+	/** Scrolled text without truncations but always in visual order, owned */
+	HBufC* iScrollingText;
+/** Title text layout */
+TAknLayoutText iTextLayout;
+/** Title text layoutline */
+TAknTextLineLayout iTextLayoutLine;
+/** Calculated length of the text in pixels */
+	TInt  iTextLength;
+/** Bitmap where text with effect is draw into */
+CFbsBitmap* iBitmap;
+/** Bitmap device where text with effect is draw into */
+CFbsBitmapDevice* iBitmapDevice;
+/** Bitmap context where text with effect is draw into */
+CFbsBitGc* iBitmapGc;
+/** Mask where texts mask with effect is draw into */
+CFbsBitmap* iMask;
+/** Mask device where texts mask with effect is draw into */
+CFbsBitmapDevice* iMaskDevice;
+/** Mask context where texts mask with effect is draw into */
+CFbsBitGc* iMaskGc;
+/**
+* Not owned. Observer, whose DrawNow() -method gets called if effect
+* has changed text outlook.
+*/
+CCoeControl* iObserver;
+/** Queue which can store multiple effects. */
+	CArrayFixFlat<SAknTitleLableEffect>* iEffectQueue;
+	/** Number of the next effect to be executed from effect queue */
+	TInt  iNextEffectInEffectQueue;
+/** The pictograph interface used to draw Japanese pictographs, not owned */
+CAknPictographInterface* iPictographInterface;
+/** Whether or not the current language is LTR (ETrue) or RTL (EFalse) */
+TBool  iWesternText;
+};
+#endif // C_AKNTITLEPANELABEL_H