Class XCoeTextDrawer

class XCoeTextDrawer;

Description

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

Members

Defined in XCoeTextDrawer:
Alignment(), ClipRect(), DrawDisplayOrderedText(), DrawText(), LineGapInPixels(), Margins(), SetAlignment(), SetClipRect(), SetLineGapInPixels(), SetMargins(), SetTextColor(), TextColor(), XCoeTextDrawer(), operator->(), operator=(), ~XCoeTextDrawer()

IMPORT_C XCoeTextDrawer(CCoeTextDrawerBase &aTextDrawer);

Description

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

IMPORT_C ~XCoeTextDrawer();

Description

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.

IMPORT_C void operator=(CCoeTextDrawerBase &aTextDrawer);

Description

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 &aTextDrawer A text drawer.

IMPORT_C void DrawText(CGraphicsContext &aGc, const TBidiText &aText, const TRect &aTextRect, const CFont &aFont) const;

Description

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 &aGc The graphics context. const TBidiText &aText TBidiText reference containing the text to be drawn. const TRect &aTextRect Rectangle text will be drawn in const CFont &aFont Font to be used.

IMPORT_C void DrawDisplayOrderedText(CGraphicsContext &aGc, const TDesC &aText, const TRect &aTextRect, const CFont &aFont) const;

Description

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 &aGc The graphics context. const TDesC &aText TDesC reference containing the text to be drawn. const TRect &aTextRect Rectangle text will be drawn in const CFont &aFont Font to be used.

IMPORT_C TRect ClipRect() const;

Description

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.

Return value

TRect The clipping rect.

IMPORT_C void SetClipRect(const TRect &aClipRect);

Description

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 &aClipRect TRect value to set iClipRect to.

inline TRgb TextColor() const;

Description

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

Return value

TRgb The color used to draw text.

inline void SetTextColor(TRgb aColor);

Description

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

Parameters

TRgb aColor The color to use to draw text.

inline TGulAlignment Alignment() const;

Description

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 value

TGulAlignment TGulAlignment value of iAlignment data member

inline void SetAlignment(const TGulAlignment &aAlignment);

Description

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 &aAlignment TGulAlignment value.

inline TMargins8 Margins() const;

Description

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

Return value

TMargins8 The margins between the text rect and the actual text, in pixels.

inline void SetMargins(const TMargins8 &aMargins);

Description

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

Parameters

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

inline TInt LineGapInPixels() const;

Description

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

Return value

TInt The gap between lines of text, in pixels.

inline void SetLineGapInPixels(TInt aLineGapInPixels);

Description

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

Parameters

TInt aLineGapInPixels The gap between lines of text, in pixels.

IMPORT_C CCoeTextDrawerBase *operator->();

Description

Deprecated.

Return value

CCoeTextDrawerBase *