williamr@2: // Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: // All rights reserved.
williamr@2: // This component and the accompanying materials are made available
williamr@4: // under the terms of "Eclipse Public License v1.0"
williamr@2: // which accompanies this distribution, and is available
williamr@4: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: //
williamr@2: // Initial Contributors:
williamr@2: // Nokia Corporation - initial contribution.
williamr@2: //
williamr@2: // Contributors:
williamr@2: //
williamr@2: // Description:
williamr@2: //
williamr@2: 
williamr@2: #ifndef __COETEXTDRAWER_H__
williamr@2: #define __COETEXTDRAWER_H__
williamr@2: 
williamr@2: #include <gulutil.h>	 
williamr@2: #include <gulalign.h>	 
williamr@2: #include <biditext.h>
williamr@2: #include <coemop.h>
williamr@2: 
williamr@2: //
williamr@2: // TEXT DRAWER CODE
williamr@2: //
williamr@2: 
williamr@2: // forward declarations
williamr@2: class CCoeTextDrawerBase;
williamr@2: class TCoeTextTypeAdaptor;
williamr@2: 
williamr@2: /**
williamr@2: This class serves as a smart-pointer handle to a CCoeTextDrawerBase-derived object, used for drawing
williamr@2: user interface text. Through the use of the CCoeControl's TextDrawer() and GetTextDrawer() methods, a
williamr@2: container control can control the text style and color used by its child controls. For example, a button
williamr@2: class can override its GetTextDrawer() method to set the text color used by its text label child control 
williamr@2: depending on the buttons state (e.g. unpressed, pressed, or dimmed).
williamr@2: 
williamr@2: The XCoeTextDrawer object manages the life of the heap allocated CCoeTextDrawerBase (deleting it or 
williamr@2: resetting it depending on whether the object is reusable or not).
williamr@2: 
williamr@2: XCoeTextDrawer objects shall be allocated on the stack in the control's Draw() method and initialized 
williamr@2: with a heap allocated CCoeTextDrawerBase object fetched from the control's skin, or from its parent or 
williamr@2: background through the CCoeControl::TextDrawer() method. 
williamr@2: 
williamr@2: Never create a CCoeTextDrawer-derived object inside your CCoeControl::Draw() method, as this is not 
williamr@2: guaranteed to work in low-memory situations. Non-reusable text drawers must only be created in your
williamr@2: control's GetTextDrawer() method, as this provides error handling in case the text drawer could not be 
williamr@2: created.
williamr@2: 
williamr@2: Hence, typical use from inside a CCoeControl's Draw() method:
williamr@2: <code>
williamr@2: XCoeTextDrawer textDrawer(TextDrawer());
williamr@2: textDrawer.SetAlignment(EHLeftVCenter);
williamr@2: textDrawer.SetMargins(iTextMargins);
williamr@2: textDrawer.DrawText(SystemGc(), *iText, iTextRect, ScreenFont(TCoeFont::NormalFont()));
williamr@2: </code>
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: class XCoeTextDrawer
williamr@2: 	{
williamr@2: public:
williamr@2: 	IMPORT_C XCoeTextDrawer(CCoeTextDrawerBase& aTextDrawer);
williamr@2: 	IMPORT_C ~XCoeTextDrawer();
williamr@2: 	
williamr@2: 	IMPORT_C void operator=(CCoeTextDrawerBase& aTextDrawer);
williamr@2: 
williamr@2: 	IMPORT_C void DrawText(CGraphicsContext& aGc, const TBidiText& aText, const TRect& aTextRect, const CFont& aFont) const;
williamr@2: 	IMPORT_C void DrawDisplayOrderedText(CGraphicsContext& aGc, const TDesC& aText, const TRect& aTextRect, const CFont& aFont) const;
williamr@2: 	
williamr@2: 	IMPORT_C void DrawTextVertical(CGraphicsContext& aGc, const TBidiText& aText, const TRect& aTextRect, const CFont& aFont, TBool aUp = ETrue) const;
williamr@2: 	IMPORT_C void DrawDisplayOrderedTextVertical(CGraphicsContext& aGc, const TDesC& aText, const TRect& aTextRect, const CFont& aFont, TBool aUp = ETrue) const;
williamr@2: 	
williamr@2: 	IMPORT_C TRect ClipRect() const;
williamr@2: 	IMPORT_C void SetClipRect(const TRect& aClipRect);
williamr@2: 
williamr@2: 	inline TRgb TextColor() const;
williamr@2: 	inline void SetTextColor(TRgb aColor);
williamr@2: 	
williamr@2: 	inline TGulAlignment Alignment() const;
williamr@2: 	inline void SetAlignment(const TGulAlignment& aAlignment);
williamr@2: 	
williamr@2: 	inline TMargins8 Margins() const;
williamr@2: 	inline void SetMargins(const TMargins8& aMargins);
williamr@2: 	
williamr@2: 	inline TInt LineGapInPixels() const;
williamr@2: 	inline void SetLineGapInPixels(TInt aLineGapInPixels);	
williamr@2: public: 
williamr@2: 	IMPORT_C CCoeTextDrawerBase *operator ->();		// deprecated	
williamr@2: private:
williamr@2: 	XCoeTextDrawer(const XCoeTextDrawer& aTextDrawer);  
williamr@2: private:	
williamr@2: 	CCoeTextDrawerBase* iTextDrawer;
williamr@2: 	TRect iClipRect;
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: // forward declaration
williamr@2: class CCoeTextDrawerBaseExt;
williamr@2: 
williamr@2: /**
williamr@2: This is the base class for all text drawers implementing different text effects (for example 
williamr@2: shadow or glowing/outlined text). The object can be created and deleted each time it's used, 
williamr@2: or Reset() and reused if it IsReusable(). The latter is recommended.
williamr@2: 
williamr@2: Note that the pure virtual DrawText() method is private. This ensures that the object is used 
williamr@2: through the XCoeTextDrawer class (which manages its life). 
williamr@2: 
williamr@2: Note also that the accessor and set methods should be used via the owning XCoeTextDrawer object,
williamr@2: and that the MObjectProvider mechanism can be used to identify the actual text drawer implementation.
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: class CCoeTextDrawerBase : public CBase, public MObjectProvider
williamr@2: 	{
williamr@2: 	friend class XCoeTextDrawer;   
williamr@2: public:
williamr@2: 	IMPORT_C ~CCoeTextDrawerBase();
williamr@2: 	IMPORT_C virtual void Reset();
williamr@2: 
williamr@2: 	/**
williamr@2: 	This method returns the main color used by the CCoeTextDrawer to draw text.
williamr@2: 	@return The color used to draw text.
williamr@2: 	*/
williamr@2: 	virtual TRgb TextColor() const = 0;
williamr@2: 	/**
williamr@2: 	This method sets the main color to use to draw text.
williamr@2: 	@param aColor The color to use to draw text.
williamr@2: 	*/
williamr@2: 	virtual void SetTextColor(TRgb aColor) = 0;
williamr@2:  
williamr@2: 	IMPORT_C TGulAlignment Alignment() const;
williamr@2: 	IMPORT_C void SetAlignment(const TGulAlignment& aAlignment);
williamr@2: 	
williamr@2: 	IMPORT_C TMargins8 Margins() const;
williamr@2: 	IMPORT_C void SetMargins(const TMargins8& aMargins);
williamr@2: 	
williamr@2: 	IMPORT_C TInt LineGapInPixels() const;
williamr@2: 	IMPORT_C void SetLineGapInPixels(TInt aLineGapInPixels);
williamr@2: public:	// public methods only for use by the owner/creator of the CCoeTextDrawerBase-derived object
williamr@2:  	IMPORT_C TBool IsReusable() const;
williamr@2: 	IMPORT_C void SetReusable(TBool aIsReusable);
williamr@2: 	
williamr@2: 	IMPORT_C void SetAppLanguage(TLanguage aAppLang);
williamr@2: protected:
williamr@2:  	IMPORT_C CCoeTextDrawerBase();
williamr@2: 	IMPORT_C TInt Construct();
williamr@2: 	IMPORT_C TGulHAlignment ActualHorizontalAlignment(const TCoeTextTypeAdaptor& aText) const;
williamr@2: private:  
williamr@2: 	/**
williamr@2: 	Any actual text drawer must implement this method to draw the text passed as argument.
williamr@2: 	The implementation must draw the text inside the text rectangle, cropped to the clipping
williamr@2: 	rectangle, and with the given margins and alignment taken into account.
williamr@2: 	
williamr@2: 	Note that the actual horizontal alignment shall depend on the script directionality. 
williamr@2: 	Calling	ActualHorizontalAlignment() will return the horizontal alignment where left and 
williamr@2: 	right has been swapped for right-to-left scripts.
williamr@2: 	*/
williamr@2: 	virtual void DrawText(CGraphicsContext& aGc, const TCoeTextTypeAdaptor& aText, const CFont& aFont, 
williamr@2: 							const TRect& aTextRect, const TRect& aClipRect) const = 0;
williamr@2: public:
williamr@2: 	IMPORT_C virtual TMargins8 EffectMargins();
williamr@2: private:
williamr@2: 	/**
williamr@2: 	Draws the text vertically inside the text rectangle, cropped to the clipping
williamr@2: 	rectangle, and with the given margins and alignment taken into account.
williamr@2: 	If aUp is ETrue, text is rotated 90 degrees anti-clockwise; EFalse, text is rotated 90 degrees clockwise.
williamr@2: 	
williamr@2: 	Note that the actual horizontal alignment shall depend on the script directionality. 
williamr@2: 	Calling	ActualHorizontalAlignment() will return the horizontal alignment where left and 
williamr@2: 	right has been swapped for right-to-left scripts.
williamr@2: 	Also note that the margines are relative to the orientation of the text.
williamr@2: 	*/
williamr@2: 	IMPORT_C virtual void DrawTextVertical(CGraphicsContext& aGc, const TCoeTextTypeAdaptor& aText, const CFont& aFont, 
williamr@2: 							const TRect& aTextRect, const TRect& aClipRect, TBool aUp) const;
williamr@2: 	IMPORT_C virtual void CCoeTextDrawerBase_Reserved3();
williamr@2: 	IMPORT_C virtual void CCoeTextDrawerBase_Reserved4();
williamr@2: 	IMPORT_C virtual void CCoeTextDrawerBase_Reserved5();
williamr@2: 	IMPORT_C virtual void CCoeTextDrawerBase_Reserved6();
williamr@2: 	IMPORT_C virtual void CCoeTextDrawerBase_Reserved7();
williamr@2: 	IMPORT_C virtual void CCoeTextDrawerBase_Reserved8();
williamr@2: 	IMPORT_C virtual void CCoeTextDrawerBase_Reserved9();
williamr@2: 	IMPORT_C virtual void CCoeTextDrawerBase_Reserved10();
williamr@2:  private:
williamr@2: 	TBool iIsReusable;	 
williamr@2: 	TGulAlignment iAlignment;
williamr@2: 	TMargins8 iMargins;
williamr@2: 	TInt iLineGap;
williamr@2: 	CCoeTextDrawerBaseExt* iExtension;
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: This class allows the XCoeTextDrawer to draw text that is in the form of a TBidiText 
williamr@2: object as well as pre-reordered new-line separated plain text descriptors. (The descriptor 
williamr@2: text is especially useful when using the XCoeTextDrawer together with the FORM component). 
williamr@2: 
williamr@2: This removes the need to implement two versions of the DrawText() method.
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: class TCoeTextTypeAdaptor
williamr@2: 	{
williamr@2: public:
williamr@2: 	IMPORT_C TCoeTextTypeAdaptor(const TDesC& aText);		// text lines separated with '\n'
williamr@2: 	IMPORT_C TCoeTextTypeAdaptor(const TBidiText& aText);	// TBidiText object
williamr@2: 	IMPORT_C TInt NumberOfLines() const;
williamr@2: 	IMPORT_C TPtrC LineOfText(TInt aLineNumber, TInt& aWidthInPixels, const CFont& aFont) const;	
williamr@2: 	IMPORT_C TBool HasRightToLeftDirectionality() const;
williamr@2: private:
williamr@2: 	enum TTextType
williamr@2: 		{
williamr@2: 		ENewlineSeparated,
williamr@2: 		EBidiText
williamr@2: 		};
williamr@2: 	const TAny* iText;
williamr@2: 	TTextType iTextType;
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: /**	
williamr@2: This is a basic text drawer without any text effects. The default text drawer that can be 
williamr@2: used if no other (device specific) text drawers has been added to the system. 
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: class CCoePlainTextDrawer : public CCoeTextDrawerBase
williamr@2: 	{
williamr@2: public:
williamr@2: 	DECLARE_TYPE_ID(0x1020831A)
williamr@2: public:
williamr@2: 	IMPORT_C static CCoePlainTextDrawer* New(TRgb aTextColor);
williamr@2: 	
williamr@2: 	IMPORT_C TRgb TextColor() const;
williamr@2: 	IMPORT_C void SetTextColor(TRgb aTextColor);
williamr@2: protected: // from MObjectProvider
williamr@2: 	IMPORT_C virtual TTypeUid::Ptr MopSupplyObject(TTypeUid aId);
williamr@2: private:  
williamr@2: 	void DrawText(CGraphicsContext& aGc, const TCoeTextTypeAdaptor& aText, const CFont& aFont, 
williamr@2: 					const TRect& aTextRect, const TRect& aClipRect) const;
williamr@2: 	void Reset();	
williamr@2: 	CCoePlainTextDrawer(TRgb aTextColor);
williamr@2: 	TInt Construct();	//lint !e1511 Suppress member hides non-virtual member
williamr@2: private:	
williamr@2: 	TRgb iTextColor;
williamr@2: 	};
williamr@2: 	
williamr@2: 
williamr@2: 
williamr@2: // Inlines		
williamr@2: 
williamr@2: /**
williamr@2: This method returns the main color used by by DrawText() and DrawDisplayOrderedText().
williamr@2: @return The color used to draw text.
williamr@2: */
williamr@2: TRgb XCoeTextDrawer::TextColor() const
williamr@2: 	{ return iTextDrawer->TextColor(); }
williamr@2: 	
williamr@2: /**
williamr@2: This method sets the main color to use by DrawText() and DrawDisplayOrderedText() to draw text.
williamr@2: @param aColor The color to use to draw text.
williamr@2: */
williamr@2: void XCoeTextDrawer::SetTextColor(TRgb aColor)
williamr@2: 	{ iTextDrawer->SetTextColor(aColor); }
williamr@2: 
williamr@2: /**
williamr@2: Returns the text alignment that will be used by DrawText() and DrawDisplayOrderedText().
williamr@2: Note that left and right alignment will be swapped for right-to-left scripts, unless
williamr@2: the alignment has been set to be absolute (see TGulAlignment).
williamr@2: 
williamr@2: @return TGulAlignment value of iAlignment data member
williamr@2: */
williamr@2: TGulAlignment XCoeTextDrawer::Alignment() const
williamr@2: 	{ return iTextDrawer->Alignment(); }
williamr@2: 
williamr@2: /**
williamr@2: Set the text alignment that will be used by DrawText() and DrawDisplayOrderedText().
williamr@2: Note that left and right alignment will be swapped for right-to-left scripts, unless
williamr@2: the alignment has been set to be absolute (see TGulAlignment).
williamr@2: 
williamr@2: @param aAlignment TGulAlignment value.  
williamr@2: */		
williamr@2: void XCoeTextDrawer::SetAlignment(const TGulAlignment& aAlignment)
williamr@2: 	{ iTextDrawer->SetAlignment(aAlignment); }
williamr@2: 
williamr@2: /**
williamr@2: Returns the text margins that will be used by DrawText() and DrawDisplayOrderedText().
williamr@2: Note that text effects may intrude on the margin.
williamr@2: 
williamr@2: @return The margins between the text rect and the actual text, in pixels.
williamr@2: */	
williamr@2: TMargins8 XCoeTextDrawer::Margins() const
williamr@2: 	{ return iTextDrawer->Margins(); }
williamr@2: 
williamr@2: /**
williamr@2: Set the text margins that will be used by DrawText() and DrawDisplayOrderedText().
williamr@2: Note that text effects may intrude on the margin, and that margins are always relative to the text orientation. 
williamr@2: 
williamr@2: @param aMargins The margins between the text rect and the actual text, in pixels.
williamr@2: */		
williamr@2: void XCoeTextDrawer::SetMargins(const TMargins8& aMargins)
williamr@2: 	{ iTextDrawer->SetMargins(aMargins); }
williamr@2: 	
williamr@2: /**
williamr@2: Returns the gap (in pixels) between lines of text. Default gap is 1 (one) pixel.
williamr@2: @return The gap between lines of text, in pixels.
williamr@2: */	
williamr@2: TInt XCoeTextDrawer::LineGapInPixels() const
williamr@2: 	{ return iTextDrawer->LineGapInPixels(); }
williamr@2: 	
williamr@2: /**
williamr@2: Set the gap (in pixels) between lines of text. Default gap is 1 (one) pixel.
williamr@2: @param aLineGapInPixels The gap between lines of text, in pixels.
williamr@2: */			
williamr@2: void XCoeTextDrawer::SetLineGapInPixels(TInt aLineGapInPixels)
williamr@2: 	{ iTextDrawer->SetLineGapInPixels(aLineGapInPixels); }
williamr@2: 
williamr@2: 		
williamr@2: #endif	// __COETEXTDRAWER_H__