1.1 --- a/epoc32/include/coetextdrawer.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/coetextdrawer.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,324 @@
1.4 -coetextdrawer.h
1.5 +// Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +// All rights reserved.
1.7 +// This component and the accompanying materials are made available
1.8 +// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
1.9 +// which accompanies this distribution, and is available
1.10 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +//
1.12 +// Initial Contributors:
1.13 +// Nokia Corporation - initial contribution.
1.14 +//
1.15 +// Contributors:
1.16 +//
1.17 +// Description:
1.18 +//
1.19 +
1.20 +#ifndef __COETEXTDRAWER_H__
1.21 +#define __COETEXTDRAWER_H__
1.22 +
1.23 +#include <gulutil.h>
1.24 +#include <gulalign.h>
1.25 +#include <biditext.h>
1.26 +#include <coemop.h>
1.27 +
1.28 +//
1.29 +// TEXT DRAWER CODE
1.30 +//
1.31 +
1.32 +// forward declarations
1.33 +class CCoeTextDrawerBase;
1.34 +class TCoeTextTypeAdaptor;
1.35 +
1.36 +/**
1.37 +This class serves as a smart-pointer handle to a CCoeTextDrawerBase-derived object, used for drawing
1.38 +user interface text. Through the use of the CCoeControl's TextDrawer() and GetTextDrawer() methods, a
1.39 +container control can control the text style and color used by its child controls. For example, a button
1.40 +class can override its GetTextDrawer() method to set the text color used by its text label child control
1.41 +depending on the buttons state (e.g. unpressed, pressed, or dimmed).
1.42 +
1.43 +The XCoeTextDrawer object manages the life of the heap allocated CCoeTextDrawerBase (deleting it or
1.44 +resetting it depending on whether the object is reusable or not).
1.45 +
1.46 +XCoeTextDrawer objects shall be allocated on the stack in the control's Draw() method and initialized
1.47 +with a heap allocated CCoeTextDrawerBase object fetched from the control's skin, or from its parent or
1.48 +background through the CCoeControl::TextDrawer() method.
1.49 +
1.50 +Never create a CCoeTextDrawer-derived object inside your CCoeControl::Draw() method, as this is not
1.51 +guaranteed to work in low-memory situations. Non-reusable text drawers must only be created in your
1.52 +control's GetTextDrawer() method, as this provides error handling in case the text drawer could not be
1.53 +created.
1.54 +
1.55 +Hence, typical use from inside a CCoeControl's Draw() method:
1.56 +<code>
1.57 +XCoeTextDrawer textDrawer(TextDrawer());
1.58 +textDrawer.SetAlignment(EHLeftVCenter);
1.59 +textDrawer.SetMargins(iTextMargins);
1.60 +textDrawer.DrawText(SystemGc(), *iText, iTextRect, ScreenFont(TCoeFont::NormalFont()));
1.61 +</code>
1.62 +
1.63 +@publishedAll
1.64 +@released
1.65 +*/
1.66 +class XCoeTextDrawer
1.67 + {
1.68 +public:
1.69 + IMPORT_C XCoeTextDrawer(CCoeTextDrawerBase& aTextDrawer);
1.70 + IMPORT_C ~XCoeTextDrawer();
1.71 +
1.72 + IMPORT_C void operator=(CCoeTextDrawerBase& aTextDrawer);
1.73 +
1.74 + IMPORT_C void DrawText(CGraphicsContext& aGc, const TBidiText& aText, const TRect& aTextRect, const CFont& aFont) const;
1.75 + IMPORT_C void DrawDisplayOrderedText(CGraphicsContext& aGc, const TDesC& aText, const TRect& aTextRect, const CFont& aFont) const;
1.76 +
1.77 + IMPORT_C void DrawTextVertical(CGraphicsContext& aGc, const TBidiText& aText, const TRect& aTextRect, const CFont& aFont, TBool aUp = ETrue) const;
1.78 + IMPORT_C void DrawDisplayOrderedTextVertical(CGraphicsContext& aGc, const TDesC& aText, const TRect& aTextRect, const CFont& aFont, TBool aUp = ETrue) const;
1.79 +
1.80 + IMPORT_C TRect ClipRect() const;
1.81 + IMPORT_C void SetClipRect(const TRect& aClipRect);
1.82 +
1.83 + inline TRgb TextColor() const;
1.84 + inline void SetTextColor(TRgb aColor);
1.85 +
1.86 + inline TGulAlignment Alignment() const;
1.87 + inline void SetAlignment(const TGulAlignment& aAlignment);
1.88 +
1.89 + inline TMargins8 Margins() const;
1.90 + inline void SetMargins(const TMargins8& aMargins);
1.91 +
1.92 + inline TInt LineGapInPixels() const;
1.93 + inline void SetLineGapInPixels(TInt aLineGapInPixels);
1.94 +public:
1.95 + IMPORT_C CCoeTextDrawerBase *operator ->(); // deprecated
1.96 +private:
1.97 + XCoeTextDrawer(const XCoeTextDrawer& aTextDrawer);
1.98 +private:
1.99 + CCoeTextDrawerBase* iTextDrawer;
1.100 + TRect iClipRect;
1.101 + };
1.102 +
1.103 +
1.104 +// forward declaration
1.105 +class CCoeTextDrawerBaseExt;
1.106 +
1.107 +/**
1.108 +This is the base class for all text drawers implementing different text effects (for example
1.109 +shadow or glowing/outlined text). The object can be created and deleted each time it's used,
1.110 +or Reset() and reused if it IsReusable(). The latter is recommended.
1.111 +
1.112 +Note that the pure virtual DrawText() method is private. This ensures that the object is used
1.113 +through the XCoeTextDrawer class (which manages its life).
1.114 +
1.115 +Note also that the accessor and set methods should be used via the owning XCoeTextDrawer object,
1.116 +and that the MObjectProvider mechanism can be used to identify the actual text drawer implementation.
1.117 +
1.118 +@publishedAll
1.119 +@released
1.120 +*/
1.121 +class CCoeTextDrawerBase : public CBase, public MObjectProvider
1.122 + {
1.123 + friend class XCoeTextDrawer;
1.124 +public:
1.125 + IMPORT_C ~CCoeTextDrawerBase();
1.126 + IMPORT_C virtual void Reset();
1.127 +
1.128 + /**
1.129 + This method returns the main color used by the CCoeTextDrawer to draw text.
1.130 + @return The color used to draw text.
1.131 + */
1.132 + virtual TRgb TextColor() const = 0;
1.133 + /**
1.134 + This method sets the main color to use to draw text.
1.135 + @param aColor The color to use to draw text.
1.136 + */
1.137 + virtual void SetTextColor(TRgb aColor) = 0;
1.138 +
1.139 + IMPORT_C TGulAlignment Alignment() const;
1.140 + IMPORT_C void SetAlignment(const TGulAlignment& aAlignment);
1.141 +
1.142 + IMPORT_C TMargins8 Margins() const;
1.143 + IMPORT_C void SetMargins(const TMargins8& aMargins);
1.144 +
1.145 + IMPORT_C TInt LineGapInPixels() const;
1.146 + IMPORT_C void SetLineGapInPixels(TInt aLineGapInPixels);
1.147 +public: // public methods only for use by the owner/creator of the CCoeTextDrawerBase-derived object
1.148 + IMPORT_C TBool IsReusable() const;
1.149 + IMPORT_C void SetReusable(TBool aIsReusable);
1.150 +
1.151 + IMPORT_C void SetAppLanguage(TLanguage aAppLang);
1.152 +protected:
1.153 + IMPORT_C CCoeTextDrawerBase();
1.154 + IMPORT_C TInt Construct();
1.155 + IMPORT_C TGulHAlignment ActualHorizontalAlignment(const TCoeTextTypeAdaptor& aText) const;
1.156 +private:
1.157 + /**
1.158 + Any actual text drawer must implement this method to draw the text passed as argument.
1.159 + The implementation must draw the text inside the text rectangle, cropped to the clipping
1.160 + rectangle, and with the given margins and alignment taken into account.
1.161 +
1.162 + Note that the actual horizontal alignment shall depend on the script directionality.
1.163 + Calling ActualHorizontalAlignment() will return the horizontal alignment where left and
1.164 + right has been swapped for right-to-left scripts.
1.165 + */
1.166 + virtual void DrawText(CGraphicsContext& aGc, const TCoeTextTypeAdaptor& aText, const CFont& aFont,
1.167 + const TRect& aTextRect, const TRect& aClipRect) const = 0;
1.168 +public:
1.169 + IMPORT_C virtual TMargins8 EffectMargins();
1.170 +private:
1.171 + /**
1.172 + Draws the text vertically inside the text rectangle, cropped to the clipping
1.173 + rectangle, and with the given margins and alignment taken into account.
1.174 + If aUp is ETrue, text is rotated 90 degrees anti-clockwise; EFalse, text is rotated 90 degrees clockwise.
1.175 +
1.176 + Note that the actual horizontal alignment shall depend on the script directionality.
1.177 + Calling ActualHorizontalAlignment() will return the horizontal alignment where left and
1.178 + right has been swapped for right-to-left scripts.
1.179 + Also note that the margines are relative to the orientation of the text.
1.180 + */
1.181 + IMPORT_C virtual void DrawTextVertical(CGraphicsContext& aGc, const TCoeTextTypeAdaptor& aText, const CFont& aFont,
1.182 + const TRect& aTextRect, const TRect& aClipRect, TBool aUp) const;
1.183 + IMPORT_C virtual void CCoeTextDrawerBase_Reserved3();
1.184 + IMPORT_C virtual void CCoeTextDrawerBase_Reserved4();
1.185 + IMPORT_C virtual void CCoeTextDrawerBase_Reserved5();
1.186 + IMPORT_C virtual void CCoeTextDrawerBase_Reserved6();
1.187 + IMPORT_C virtual void CCoeTextDrawerBase_Reserved7();
1.188 + IMPORT_C virtual void CCoeTextDrawerBase_Reserved8();
1.189 + IMPORT_C virtual void CCoeTextDrawerBase_Reserved9();
1.190 + IMPORT_C virtual void CCoeTextDrawerBase_Reserved10();
1.191 + private:
1.192 + TBool iIsReusable;
1.193 + TGulAlignment iAlignment;
1.194 + TMargins8 iMargins;
1.195 + TInt iLineGap;
1.196 + CCoeTextDrawerBaseExt* iExtension;
1.197 + };
1.198 +
1.199 +
1.200 +/**
1.201 +This class allows the XCoeTextDrawer to draw text that is in the form of a TBidiText
1.202 +object as well as pre-reordered new-line separated plain text descriptors. (The descriptor
1.203 +text is especially useful when using the XCoeTextDrawer together with the FORM component).
1.204 +
1.205 +This removes the need to implement two versions of the DrawText() method.
1.206 +
1.207 +@publishedAll
1.208 +@released
1.209 +*/
1.210 +class TCoeTextTypeAdaptor
1.211 + {
1.212 +public:
1.213 + IMPORT_C TCoeTextTypeAdaptor(const TDesC& aText); // text lines separated with '\n'
1.214 + IMPORT_C TCoeTextTypeAdaptor(const TBidiText& aText); // TBidiText object
1.215 + IMPORT_C TInt NumberOfLines() const;
1.216 + IMPORT_C TPtrC LineOfText(TInt aLineNumber, TInt& aWidthInPixels, const CFont& aFont) const;
1.217 + IMPORT_C TBool HasRightToLeftDirectionality() const;
1.218 +private:
1.219 + enum TTextType
1.220 + {
1.221 + ENewlineSeparated,
1.222 + EBidiText
1.223 + };
1.224 + const TAny* iText;
1.225 + TTextType iTextType;
1.226 + };
1.227 +
1.228 +
1.229 +/**
1.230 +This is a basic text drawer without any text effects. The default text drawer that can be
1.231 +used if no other (device specific) text drawers has been added to the system.
1.232 +
1.233 +@publishedAll
1.234 +@released
1.235 +*/
1.236 +class CCoePlainTextDrawer : public CCoeTextDrawerBase
1.237 + {
1.238 +public:
1.239 + DECLARE_TYPE_ID(0x1020831A)
1.240 +public:
1.241 + IMPORT_C static CCoePlainTextDrawer* New(TRgb aTextColor);
1.242 +
1.243 + IMPORT_C TRgb TextColor() const;
1.244 + IMPORT_C void SetTextColor(TRgb aTextColor);
1.245 +protected: // from MObjectProvider
1.246 + IMPORT_C virtual TTypeUid::Ptr MopSupplyObject(TTypeUid aId);
1.247 +private:
1.248 + void DrawText(CGraphicsContext& aGc, const TCoeTextTypeAdaptor& aText, const CFont& aFont,
1.249 + const TRect& aTextRect, const TRect& aClipRect) const;
1.250 + void Reset();
1.251 + CCoePlainTextDrawer(TRgb aTextColor);
1.252 + TInt Construct(); //lint !e1511 Suppress member hides non-virtual member
1.253 +private:
1.254 + TRgb iTextColor;
1.255 + };
1.256 +
1.257 +
1.258 +
1.259 +// Inlines
1.260 +
1.261 +/**
1.262 +This method returns the main color used by by DrawText() and DrawDisplayOrderedText().
1.263 +@return The color used to draw text.
1.264 +*/
1.265 +TRgb XCoeTextDrawer::TextColor() const
1.266 + { return iTextDrawer->TextColor(); }
1.267 +
1.268 +/**
1.269 +This method sets the main color to use by DrawText() and DrawDisplayOrderedText() to draw text.
1.270 +@param aColor The color to use to draw text.
1.271 +*/
1.272 +void XCoeTextDrawer::SetTextColor(TRgb aColor)
1.273 + { iTextDrawer->SetTextColor(aColor); }
1.274 +
1.275 +/**
1.276 +Returns the text alignment that will be used by DrawText() and DrawDisplayOrderedText().
1.277 +Note that left and right alignment will be swapped for right-to-left scripts, unless
1.278 +the alignment has been set to be absolute (see TGulAlignment).
1.279 +
1.280 +@return TGulAlignment value of iAlignment data member
1.281 +*/
1.282 +TGulAlignment XCoeTextDrawer::Alignment() const
1.283 + { return iTextDrawer->Alignment(); }
1.284 +
1.285 +/**
1.286 +Set the text alignment that will be used by DrawText() and DrawDisplayOrderedText().
1.287 +Note that left and right alignment will be swapped for right-to-left scripts, unless
1.288 +the alignment has been set to be absolute (see TGulAlignment).
1.289 +
1.290 +@param aAlignment TGulAlignment value.
1.291 +*/
1.292 +void XCoeTextDrawer::SetAlignment(const TGulAlignment& aAlignment)
1.293 + { iTextDrawer->SetAlignment(aAlignment); }
1.294 +
1.295 +/**
1.296 +Returns the text margins that will be used by DrawText() and DrawDisplayOrderedText().
1.297 +Note that text effects may intrude on the margin.
1.298 +
1.299 +@return The margins between the text rect and the actual text, in pixels.
1.300 +*/
1.301 +TMargins8 XCoeTextDrawer::Margins() const
1.302 + { return iTextDrawer->Margins(); }
1.303 +
1.304 +/**
1.305 +Set the text margins that will be used by DrawText() and DrawDisplayOrderedText().
1.306 +Note that text effects may intrude on the margin, and that margins are always relative to the text orientation.
1.307 +
1.308 +@param aMargins The margins between the text rect and the actual text, in pixels.
1.309 +*/
1.310 +void XCoeTextDrawer::SetMargins(const TMargins8& aMargins)
1.311 + { iTextDrawer->SetMargins(aMargins); }
1.312 +
1.313 +/**
1.314 +Returns the gap (in pixels) between lines of text. Default gap is 1 (one) pixel.
1.315 +@return The gap between lines of text, in pixels.
1.316 +*/
1.317 +TInt XCoeTextDrawer::LineGapInPixels() const
1.318 + { return iTextDrawer->LineGapInPixels(); }
1.319 +
1.320 +/**
1.321 +Set the gap (in pixels) between lines of text. Default gap is 1 (one) pixel.
1.322 +@param aLineGapInPixels The gap between lines of text, in pixels.
1.323 +*/
1.324 +void XCoeTextDrawer::SetLineGapInPixels(TInt aLineGapInPixels)
1.325 + { iTextDrawer->SetLineGapInPixels(aLineGapInPixels); }
1.326 +
1.327 +
1.328 +#endif // __COETEXTDRAWER_H__