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(TInt)const method.

Never create a CCoeTextDrawer-derived object inside your CCoeControl::Draw(const TRect &)const 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()constReturns the text alignment that will be used by XCoeTextDrawer::DrawText(CGraphi...
• ClipRect()constReturn the clip rect that will be used by XCoeTextDrawer::DrawText(CGraphicsCont...
• DrawDisplayOrderedText(CGraphicsContext &,const TDesC &,const TRect &,const CFont &)constLow level text drawing is always performed left-to-right on the screen. This mea...
• DrawDisplayOrderedTextVertical(CGraphicsContext &,const TDesC &,const TRect &,const CFont &,TBool)constLow level text drawing is always performed left-to-right on the screen. This mea...
• DrawText(CGraphicsContext &,const TBidiText &,const TRect &,const CFont &)constCall this method to draw text contained i a TBidiText object. This is the recomm...
• DrawTextVertical(CGraphicsContext &,const TBidiText &,const TRect &,const CFont &,TBool)constCall this method to draw vertical text contained in a TBidiText object. This is ...
• 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 XCoeTextDrawer::DrawText(CGraphics...
• SetAlignment(const TGulAlignment &)Set the text alignment that will be used by XCoeTextDrawer::DrawText(CGraphicsCo...
• SetClipRect(const TRect &)Set the clip rect that will be used by XCoeTextDrawer::DrawText(CGraphicsContext...
• 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 XCoeTextDrawer::DrawText(CGraphicsCont...
• SetTextColor(TRgb)This method sets the main color to use by XCoeTextDrawer::DrawText(CGraphicsCont...
• TextColor()constThis method returns the main color used by by XCoeTextDrawer::DrawText(CGraphics...
• XCoeTextDrawer(CCoeTextDrawerBase &)Use this constructor to create a XCoeTextDrawer object on the stack, inside your...
• operator->()Deprecated.
• operator=(CCoeTextDrawerBase &)Assignment operator for CCoeTextDrawerBase objects.
• ~XCoeTextDrawer()Destructor. The XCoeTextDrawer object work as a smart-pointer object to the CCoe...

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(TInt)const. 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(CCoeTextDrawerBase *&,const CCoeControl *,TInt)const method. Inside it you can create a new CCoeTextDrawerBase object or change the properties of the CCoeTextDrawerBase object passed to it.

Parameters

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

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 XCoeTextDrawer::SetAlignment(const TGulAlignment &), XCoeTextDrawer::SetMargins(const TMargins8 &), and XCoeTextDrawer::SetClipRect(const TRect &).

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

Parameters

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

IMPORT_C void DrawTextVertical(CGraphicsContext &aGc, const TBidiText &aText, const TRect &aTextRect, const CFont &aFont, TBool aUp=ETrue) const;

Description

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 XCoeTextDrawer::SetAlignment(const TGulAlignment &), XCoeTextDrawer::SetMargins(const TMargins8 &), and XCoeTextDrawer::SetClipRect(const TRect &).

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

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

Parameters

See also:

• XCoeTextDrawer::SetClipRect(const TRect &)Set the clip rect that will be used by XCoeTextDrawer::DrawText(CGraphicsContext...

IMPORT_C void DrawDisplayOrderedTextVertical(CGraphicsContext &aGc, const TDesC &aText, const TRect &aTextRect, const CFont &aFont, TBool aUp=ETrue) 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.

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

Parameters

IMPORT_C TRect ClipRect() const;

Description

Return the clip rect that will be used by XCoeTextDrawer::DrawText(CGraphicsContext &,const TBidiText &,const TRect &,const CFont &)const and XCoeTextDrawer::DrawDisplayOrderedText(CGraphicsContext &,const TDesC &,const TRect &,const CFont &)const. Any text falling outside this rectangle will not be visible. This is used to crop text.

Return value

IMPORT_C void SetClipRect(const TRect &aClipRect);

Description

Set the clip rect that will be used by XCoeTextDrawer::DrawText(CGraphicsContext &,const TBidiText &,const TRect &,const CFont &)const and XCoeTextDrawer::DrawDisplayOrderedText(CGraphicsContext &,const TDesC &,const TRect &,const CFont &)const. Any text falling outside this rectangle will not be visible. This is used to crop text.

Parameters

inline TRgb TextColor() const;

Description

This method returns the main color used by by XCoeTextDrawer::DrawText(CGraphicsContext &,const TBidiText &,const TRect &,const CFont &)const and XCoeTextDrawer::DrawDisplayOrderedText(CGraphicsContext &,const TDesC &,const TRect &,const CFont &)const.

Return value

inline void SetTextColor(TRgb aColor);

Description

This method sets the main color to use by XCoeTextDrawer::DrawText(CGraphicsContext &,const TBidiText &,const TRect &,const CFont &)const and XCoeTextDrawer::DrawDisplayOrderedText(CGraphicsContext &,const TDesC &,const TRect &,const CFont &)const to draw text.

Parameters

inline TGulAlignment Alignment() const;

Description

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

inline void SetAlignment(const TGulAlignment &aAlignment);

Description

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

inline TMargins8 Margins() const;

Description

Returns the text margins that will be used by XCoeTextDrawer::DrawText(CGraphicsContext &,const TBidiText &,const TRect &,const CFont &)const and XCoeTextDrawer::DrawDisplayOrderedText(CGraphicsContext &,const TDesC &,const TRect &,const CFont &)const. Note that text effects may intrude on the margin.

Return value

inline void SetMargins(const TMargins8 &aMargins);

Description

Set the text margins that will be used by XCoeTextDrawer::DrawText(CGraphicsContext &,const TBidiText &,const TRect &,const CFont &)const and XCoeTextDrawer::DrawDisplayOrderedText(CGraphicsContext &,const TDesC &,const TRect &,const CFont &)const. Note that text effects may intrude on the margin, and that margins are always relative to the text orientation.

Parameters

inline TInt LineGapInPixels() const;

Description

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

Return value

inline void SetLineGapInPixels(TInt aLineGapInPixels);

Description

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

Parameters

IMPORT_C CCoeTextDrawerBase* operator->();

Description

Deprecated.

Return value