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