XCoeTextDrawer Class Reference

class XCoeTextDrawer

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()));

Public Member Functions
XCoeTextDrawer(CCoeTextDrawerBase &)
~XCoeTextDrawer()
TGulAlignment Alignment()
IMPORT_C TRectClipRect()
IMPORT_C voidDrawDisplayOrderedText(CGraphicsContext &, const TDesC &, const TRect &, const CFont &)
IMPORT_C voidDrawDisplayOrderedTextVertical(CGraphicsContext &, const TDesC &, const TRect &, const CFont &, TBool)
IMPORT_C voidDrawText(CGraphicsContext &, const TBidiText &, const TRect &, const CFont &)
IMPORT_C voidDrawTextVertical(CGraphicsContext &, const TBidiText &, const TRect &, const CFont &, TBool)
TInt LineGapInPixels()
TMargins8 Margins()
voidSetAlignment(const TGulAlignment &)
IMPORT_C voidSetClipRect(const TRect &)
voidSetLineGapInPixels(TInt)
voidSetMargins(const TMargins8 &)
voidSetTextColor(TRgb)
TRgb TextColor()
IMPORT_C CCoeTextDrawerBase *operator->()
IMPORT_C voidoperator=(CCoeTextDrawerBase &)
Private Member Functions
XCoeTextDrawer(const XCoeTextDrawer &)
Private Attributes
TRect iClipRect
CCoeTextDrawerBase *iTextDrawer

Constructor & Destructor Documentation

XCoeTextDrawer(CCoeTextDrawerBase &)

IMPORT_CXCoeTextDrawer(CCoeTextDrawerBase &aTextDrawer)

Use this constructor to create a XCoeTextDrawer object on the stack, inside your control's Draw() method. The XCoeTextDrawer object will work as a smart-pointer to the CCoeTextDrawerBase object, managing its life. Get the CCoeTextDrawerBase-derived object to use by calling CCoeControl::TextDrawer(). Do not create a new CCoeTextDrawerBase-derived object inside the Draw() method. If you want to change the text drawer used by the control or any of the control's children, override the CCoeControl::GetTextDrawer() method. Inside it you can create a new CCoeTextDrawerBase object or change the properties of the CCoeTextDrawerBase object passed to it.

Parameters

CCoeTextDrawerBase & aTextDrawer

XCoeTextDrawer(const XCoeTextDrawer &)

XCoeTextDrawer(const XCoeTextDrawer &aTextDrawer)[private]

An XCoeTextDrawer object should not be copied as only one handle should exist to a CCoeTextDrawer. Therefore this copy constructor is private and just contains a panic statement.

Parameters

const XCoeTextDrawer & aTextDrawer

~XCoeTextDrawer()

IMPORT_C~XCoeTextDrawer()

Destructor. The XCoeTextDrawer object work as a smart-pointer object to the CCoeTextDrawerBase object actually performing the text drawing. The XCoeTextDrawer object shall be allocated on the stack (i.e. not using "new") in the CCoeControl's Draw() method. Once the XCoeTextDrawer object goes out of scope, this destructor will be called. It will call Reset() on the CCoeTextDrawerBase object, if it was been set to be resuable by its owner. If not, the CCoeTextDrawerBase object will be deleted. Note that it is up to the creator/owner of the CCoeTextDrawerBase to decide whether it shall be reusable or not. A user of the XCoeTextDrawer must not change the re-use'ness of the CCoeTextDrawerBase.

Member Functions Documentation

Alignment()

TGulAlignment Alignment()const [inline]

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).

ClipRect()

IMPORT_C TRectClipRect()const

Return the clip rect that will be used by DrawText() and DrawDisplayOrderedText(). Any text falling outside this rectangle will not be visible. This is used to crop text.

DrawDisplayOrderedText(CGraphicsContext &, const TDesC &, const TRect &, const CFont &)

IMPORT_C voidDrawDisplayOrderedText(CGraphicsContext &aGc,
const TDesC &aText,
const TRect &aTextRect,
const CFont &aFont
)const

Low level text drawing is always performed left-to-right on the screen. This means that for any script with right-to-left directionality (like Arabic), the in-memory order of the glyphs has to be changed (reordered) from the logical order (start of sentence first, before end of sentence) to the display order (end of sentence before (i.e. left of) start of sentence). This operation is performed by TBidiText.

However, sometimes text is reordered through some other means than the TBidiText class. In these cases, this method can be used to draw the text contained in a descriptor object in the same order (left-to-right) as it appears in the descriptor memory. I.e. this method assumes that the text has already been changed into the display order. If this is not the case, and the text is in a right-to-left script, it will come out backwards.

Parameters

CGraphicsContext & aGcThe graphics context.
const TDesC & aTextTDesC reference containing the text to be drawn.
const TRect & aTextRectRectangle text will be drawn in
const CFont & aFontFont to be used.

DrawDisplayOrderedTextVertical(CGraphicsContext &, const TDesC &, const TRect &, const CFont &, TBool)

IMPORT_C voidDrawDisplayOrderedTextVertical(CGraphicsContext &aGc,
const TDesC &aText,
const TRect &aTextRect,
const CFont &aFont,
TBoolaUp = ETrue
)const

Low level text drawing is always performed left-to-right on the screen. This means that for any script with right-to-left directionality (like Arabic), the in-memory order of the glyphs has to be changed (reordered) from the logical order (start of sentence first, before end of sentence) to the display order (end of sentence before (i.e. left of) start of sentence). This operation is performed by TBidiText.

However, sometimes text is reordered through some other means than the TBidiText class. In these cases, this method can be used to draw the text contained in a descriptor object in the same order (left-to-right) as it appears in the descriptor memory. I.e. this method assumes that the text has already been changed into the display order. If this is not the case, and the text is in a right-to-left script, it will come out backwards.

Note that the margines are relative to the orientation of the text.

Parameters

CGraphicsContext & aGcThe graphics context.
const TDesC & aTextTDesC reference containing the text to be drawn.
const TRect & aTextRectRectangle text will be drawn in
const CFont & aFontFont to be used.
TBool aUp = ETrue

DrawText(CGraphicsContext &, const TBidiText &, const TRect &, const CFont &)

IMPORT_C voidDrawText(CGraphicsContext &aGc,
const TBidiText &aText,
const TRect &aTextRect,
const CFont &aFont
)const

Call this method to draw text contained i a TBidiText object. This is the recommended way of drawing any widget text, as it will manage both left-to-right scripts like English as well as right-to-left scripts such as Arabic and Hebrew.

Before calling this method, be sure to set the text alignment, margins, clip rect, etc using the XCoeTextDrawer methods SetAlignment(), SetMargins(), and SetClipRect().

Note that before a TBidiText text can be drawn, it has to be line-broken using TBidiText::WrapText() with a wrap width that match the text rect minus margins.

Parameters

CGraphicsContext & aGcThe graphics context.
const TBidiText & aTextTBidiText reference containing the text to be drawn.
const TRect & aTextRectRectangle text will be drawn in
const CFont & aFontFont to be used.

DrawTextVertical(CGraphicsContext &, const TBidiText &, const TRect &, const CFont &, TBool)

IMPORT_C voidDrawTextVertical(CGraphicsContext &aGc,
const TBidiText &aText,
const TRect &aTextRect,
const CFont &aFont,
TBoolaUp = ETrue
)const

Call this method to draw vertical text contained in a TBidiText object. This is the recommended way of drawing any widget text, as it will manage both left-to-right scripts like English as well as right-to-left scripts such as Arabic and Hebrew.

Before calling this method, be sure to set the text alignment, margins, clip rect, etc using the XCoeTextDrawer methods SetAlignment(), SetMargins(), and SetClipRect().

Note that before a TBidiText text can be drawn, it has to be line-broken using TBidiText::WrapText() with a wrap width that match the text rect minus margins.

Also note that the margines are relative to the orientation of the text.

XCoeTextDrawer::SetClipRect

Parameters

CGraphicsContext & aGcThe graphics context.
const TBidiText & aTextTBidiText reference containing the text to be drawn.
const TRect & aTextRectRectangle text will be drawn in
const CFont & aFontFont to be used.
TBool aUp = ETrueETrue, text is rotated 90 degrees anti-clockwise; EFalse, text is rotated 90 degrees clockwise.

LineGapInPixels()

TInt LineGapInPixels()const [inline]

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

Margins()

TMargins8 Margins()const [inline]

Returns the text margins that will be used by DrawText() and DrawDisplayOrderedText(). Note that text effects may intrude on the margin.

SetAlignment(const TGulAlignment &)

voidSetAlignment(const TGulAlignment &aAlignment)[inline]

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).

Parameters

const TGulAlignment & aAlignmentTGulAlignment value.

SetClipRect(const TRect &)

IMPORT_C voidSetClipRect(const TRect &aClipRect)

Set the clip rect that will be used by DrawText() and DrawDisplayOrderedText(). Any text falling outside this rectangle will not be visible. This is used to crop text.

Parameters

const TRect & aClipRectTRect value to set iClipRect to.

SetLineGapInPixels(TInt)

voidSetLineGapInPixels(TIntaLineGapInPixels)[inline]

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

Parameters

TInt aLineGapInPixelsThe gap between lines of text, in pixels.

SetMargins(const TMargins8 &)

voidSetMargins(const TMargins8 &aMargins)[inline]

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.

Parameters

const TMargins8 & aMarginsThe margins between the text rect and the actual text, in pixels.

SetTextColor(TRgb)

voidSetTextColor(TRgbaColor)[inline]

This method sets the main color to use by DrawText() and DrawDisplayOrderedText() to draw text.

Parameters

TRgb aColorThe color to use to draw text.

TextColor()

TRgb TextColor()const [inline]

This method returns the main color used by by DrawText() and DrawDisplayOrderedText().

operator->()

IMPORT_C CCoeTextDrawerBase *operator->()

Deprecated.

operator=(CCoeTextDrawerBase &)

IMPORT_C voidoperator=(CCoeTextDrawerBase &aTextDrawer)

Assignment operator for CCoeTextDrawerBase objects.

Due to compiler defect/feature, this method may not work. I.e. if XCoeTextDrawer textDrawer = TextDrawer(); does not compile, restate as XCoeTextDrawer textDrawer(TextDrawer());

Parameters

CCoeTextDrawerBase & aTextDrawerA text drawer.

Member Data Documentation

TRect iClipRect

TRect iClipRect[private]

CCoeTextDrawerBase * iTextDrawer

CCoeTextDrawerBase *iTextDrawer[private]