Class CCoeTextDrawerBase

class CCoeTextDrawerBase : public CBase, public MObjectProvider;

Description

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 CCoeTextDrawerBase::Reset() and reused if it CCoeTextDrawerBase::IsReusable()const. The latter is recommended.

Note that the pure virtual CCoeTextDrawerBase::DrawText(CGraphicsContext &,const TCoeTextTypeAdaptor &,const CFont &,const TRect &,const TRect &)const 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.

Derivation

• MObjectProvider - An interface that allows an object to be part of a network of object providers.
• CBase - Base class for all classes to be instantiated on the heap.

• CCoeTextDrawerBase - This is the base class for all text drawers implementing different text effects ...

Members

Defined in CCoeTextDrawerBase:

• ActualHorizontalAlignment(const TCoeTextTypeAdaptor &)constThis method returns the actual (absolute) horizontal text alignment to be used w...
• Alignment()constReturns the text alignment that will be used by CCoeTextDrawerBase::DrawText(CGr...
• CCoeTextDrawerBase()Constructor.
• Construct()Second phase object construction. Note that this method is non-leaving as it may...
• DrawText(CGraphicsContext &,const TCoeTextTypeAdaptor &,const CFont &,const TRect &,const TRect &)constAny actual text drawer must implement this method to draw the text passed as arg...
• DrawTextVertical(CGraphicsContext &,const TCoeTextTypeAdaptor &,const CFont &,const TRect &,const TRect &,TBool)constDraws the text vertically inside the text rectangle, cropped to the clipping rec...
• EffectMargins()Any text drawer implementation must override this method, returning the "ma...
• IsReusable()constReturns whether the CCoeTextDrawerBase-derived text drawer object has been set t...
• LineGapInPixels()constReturns the gap (in pixels) between lines of text. Default gap is 1 (one) pixel.
• Margins()constReturns the text margins that will be used by CCoeTextDrawerBase::DrawText(CGrap...
• Reset()This method is called from the destructor of the XCoeTextDrawer object managing ...
• SetAlignment(const TGulAlignment &)Set the text alignment that will be used by CCoeTextDrawerBase::DrawText(CGraphi...
• SetAppLanguage(TLanguage)Unless absolute horizontal aligment has been selected (see TGulAlignment), the a...
• SetLineGapInPixels(TInt)Set the gap (in pixels) between lines of text. Default gap is 1 (one) pixel.
• SetMargins(const TMargins8 &)Set the text margins that will be used by CCoeTextDrawerBase::DrawText(CGraphics...
• SetReusable(TBool)Set whether the text drawer is reusable or not. A reusable text drawer will be r...
• SetTextColor(TRgb)This method sets the main color to use to draw text.
• TextColor()constThis method returns the main color used by the CCoeTextDrawer to draw text.
• ~CCoeTextDrawerBase()Destructor.

Inherited from CBase:

• Delete(CBase *)Deletes the specified object.
• Extension_(TUint,TAny *&,TAny *)Extension function
• operator new(TUint)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TAny *)Initialises the object to binary zeroes.
• operator new(TUint,TLeave)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TLeave,TUint)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TUint)Allocates the object from the heap and then initialises its contents to binary z...

Inherited from MObjectProvider:

• MopGetObject(T *&)Gets an object of the type defined by the template parameter.
• MopGetObjectNoChaining(T *&)Gets an object of the type defined by the template parameter.

IMPORT_C ~CCoeTextDrawerBase();

Description

Destructor.

protected: IMPORT_C CCoeTextDrawerBase();

Description

Constructor.

IMPORT_C virtual void Reset();

Description

This method is called from the destructor of the XCoeTextDrawer object managing the life of the CCoeTextDrawerBase object, if the CCoeTextDrawerBase object has been set to be reusable (by its owner calling CCoeTextDrawerBase::SetReusable(TBool)).

Any derived class must override this method to reset its drawing parameters to their defaults, so that the object is ready to be used again. Any overriding implementation must call the base implementation as well.

virtual TRgb TextColor() const=0;

Description

This method returns the main color used by the CCoeTextDrawer to draw text.

Return value

virtual void SetTextColor(TRgb aColor)=0;

Description

This method sets the main color to use to draw text.

Parameters

IMPORT_C TGulAlignment Alignment() const;

Description

Returns the text alignment that will be used by CCoeTextDrawerBase::DrawText(CGraphicsContext &,const TCoeTextTypeAdaptor &,const CFont &,const TRect &,const TRect &)const 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).

A typical user of the text drawer mechanism will use the XCoeTextDrawer version of this API.

Return value

IMPORT_C void SetAlignment(const TGulAlignment &aAlignment);

Description

Set the text alignment that will be used by CCoeTextDrawerBase::DrawText(CGraphicsContext &,const TCoeTextTypeAdaptor &,const CFont &,const TRect &,const TRect &)const 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).

A typical user of the text drawer mechanism will use the XCoeTextDrawer version of this API.

Parameters

IMPORT_C TMargins8 Margins() const;

Description

Returns the text margins that will be used by CCoeTextDrawerBase::DrawText(CGraphicsContext &,const TCoeTextTypeAdaptor &,const CFont &,const TRect &,const TRect &)const and DrawDisplayOrderedText().

A typical user of the text drawer mechanism will use the XCoeTextDrawer version of this API.

Return value

IMPORT_C void SetMargins(const TMargins8 &aMargins);

Description

Set the text margins that will be used by CCoeTextDrawerBase::DrawText(CGraphicsContext &,const TCoeTextTypeAdaptor &,const CFont &,const TRect &,const TRect &)const and DrawDisplayOrderedText().

A typical user of the text drawer mechanism will use the XCoeTextDrawer version of this API.

Parameters

IMPORT_C TInt LineGapInPixels() const;

Description

Returns the gap (in pixels) between lines of text. Default gap is 1 (one) pixel.

A typical user of the text drawer mechanism will use the XCoeTextDrawer version of this API.

Return value

IMPORT_C void SetLineGapInPixels(TInt aLineGapInPixels);

Description

Set the gap (in pixels) between lines of text. Default gap is 1 (one) pixel.

A typical user of the text drawer mechanism will use the XCoeTextDrawer version of this API.

Parameters

IMPORT_C TBool IsReusable() const;

Description

Returns whether the CCoeTextDrawerBase-derived text drawer object has been set to be reusable or not. If reusable, the text drawer is assumed to have an owner that will delete it when appropriate. If not reusable, the XCoeTextDrawer will delete it in its destructor.

Return value

IMPORT_C void SetReusable(TBool aIsReusable);

Description

Set whether the text drawer is reusable or not. A reusable text drawer will be reset (through a call to CCoeTextDrawerBase::Reset()) rather than deleted when the XCoeTextDrawer referring to it is deleted. This decision has to be made by the creator of the CCoeTextDrawerBase object. I.e. this method must not be called by a mere user of the XCoeTextDrawer.

Parameters

IMPORT_C void SetAppLanguage(TLanguage aAppLang);

Description

Unless absolute horizontal aligment has been selected (see TGulAlignment), the actual horizontal text alignment used when drawing text depends on whether the directionality of the scrip is left-to-right or right-to-left. In the latter case left and right is swapped. By default, the directionality of the actual text being drawn will define whether the horizontal alignment will be swapped or not. However, if (as recommended) the directionality of the application's main language shall be considered instead (rather than the directionality of the text being printed at the moment), then call this method.

If ELangNone is specified, the text drawer will be reset to swap horizontal alignment depending on the directionality of the text being printed.

Parameters

protected: IMPORT_C TInt Construct();

Description

Second phase object construction. Note that this method is non-leaving as it may be called indirectly from a Draw() method, which must not leave.

Return value

protected: IMPORT_C TGulHAlignment ActualHorizontalAlignment(const TCoeTextTypeAdaptor &aText) const;

Description

This method returns the actual (absolute) horizontal text alignment to be used when drawing text in any CCoeTextDrawerBase-derived CCoeTextDrawerBase::DrawText(CGraphicsContext &,const TCoeTextTypeAdaptor &,const CFont &,const TRect &,const TRect &)const implementation. The actual alignment depends on the application language directionality if the application language has been set calling CCoeTextDrawerBase::SetAppLanguage(TLanguage), or otherwise on the directionality of the actual text being printed. If the directionality is right-to-left (and the horizontal alignment has not been set to be absolute, using TGulAlignment::SetAbsoluteHAlignment(TBool)), left and right alignment (set using XCoeTextDrawer::SetAlignment(const TGulAlignment &)) will be swapped.

Parameters

Return value

private: virtual void DrawText(CGraphicsContext &aGc, const TCoeTextTypeAdaptor &aText, const CFont &aFont, const TRect &aTextRect, const TRect &aClipRect) const=0;

Description

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 CCoeTextDrawerBase::ActualHorizontalAlignment(const TCoeTextTypeAdaptor &)const will return the horizontal alignment where left and right has been swapped for right-to-left scripts.

Parameters

IMPORT_C virtual TMargins8 EffectMargins();

Description

Any text drawer implementation must override this method, returning the "margins" that the text effect will add to the text extent. I.e. a one-pixel drop-shadow to the lower right will add an effect margin of TMargins8(0,0,1,1), while a one-pixel all-around outline will add an effect margin of TMargins8(1,1,1,1).

Return value

private: IMPORT_C virtual void DrawTextVertical(CGraphicsContext &aGc, const TCoeTextTypeAdaptor &aText, const CFont &aFont, const TRect &aTextRect, const TRect &aClipRect, TBool aUp) const;

Description

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 CCoeTextDrawerBase::ActualHorizontalAlignment(const TCoeTextTypeAdaptor &)const 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.

Parameters