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