/*
* 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