Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]



Location: BidiText.h
Link against: gdi.lib

Class TBidiText

class TBidiText;

Description

This class works as a replacement for HBufC in those cases where a small amount of text is being formatted simply. The text must be all of one style and broken into lines of all the same length. The number of lines and the text itself is specified on construction, and the text may then be re-broken, re-truncated and re-drawn with non-leaving functions.

Members

Defined in TBidiText:
Directionality(), DisplayText(), DrawText(), DrawText(), DrawText(), ELeftToRight, EPanicRunArrayNull, ERightToLeft, LineOfDisplayText(), MinimumSize(), NewL(), NewL(), NewL(), NumberOfLinesInDisplayText(), ScriptDirectionality(), SetText(), SetText(), SetTruncationChar(), TDirectionality, TPanicCodes, Text(), TextDirectionality(), TruncationChar(), WrapText(), WrapText(), WrappingWidth()


Construction and destruction


NewL()

static IMPORT_C TBidiText *NewL(TInt aReservedMaxLength, TInt aMaxLines);

Description

Creates a bidirectional text object with enough room for up to aReservedMaxLength number of characters. The number of characters that will actually fit (when calling SetText()) might be slightly less than aReservedMaxLength, as each change between a left-to-right and a right-to-left sub-string (and the other way around) needs about two characters worth of memory.

Parameters

TInt aReservedMaxLength

The maximum number of characters.

TInt aMaxLines

The maximum number of lines that this text will need to be split into. Must be at least 1, but should not be too large, as each potential line takes an extra 8 bytes of memory.

Return value

TBidiText *

The newly constructed object.


NewL()

static IMPORT_C TBidiText *NewL(const TDesC &aText, TInt aMaxLines);

Description

Creates a bidirectional text object with directionality determined by the text itself. Use this for text that has been obtained from a resource file.

Parameters

const TDesC &aText

The text in logical order.

TInt aMaxLines

The maximum number of lines that this text will need to be split into. Must be at least 1, but should not be too large, as each potential line takes an extra 8 bytes of memory.

Return value

TBidiText *

The newly constructed object.


NewL()

static IMPORT_C TBidiText *NewL(const TDesC &aText, TInt aMaxLines, TDirectionality aDirectionality);

Description

Creates a bidirectional text object with directionality determined by aDirectionality. Use this for text that has come from user input.

Parameters

const TDesC &aText

The text in logical order.

TInt aMaxLines

The maximum number of lines that this text will need to be split into. Must be at least 1, but should not be too large, as each potential line takes an extra 8 bytes of memory.

TDirectionality aDirectionality

Direction to use.

Return value

TBidiText *

The newly constructed object.

[Top]


Member functions


ScriptDirectionality()

static IMPORT_C TDirectionality ScriptDirectionality(TLanguage aLanguage);

Description

Returns the directionality of a given language.

Parameters

TLanguage aLanguage

Language.

Return value

TDirectionality

The directionality of the given language.


TextDirectionality()

static IMPORT_C TDirectionality TextDirectionality(const TDesC &aText, TBool *aFound=0);

Description

Reports the implicit directionality of a piece of text.

Parameters

const TDesC &aText

The text to be examined.

TBool *aFound

If non-null, returns ETrue if there were any strongly directional characters and EFalse if there were none. If a piece of text is spread over several descriptors, They need to be queried in sequence until one returns ETrue in aFound.

Return value

TDirectionality

The directionality implicit in aText. 131


SetText()

IMPORT_C TInt SetText(const TDesC &aText, RRunInfoArray &aRunInfoArray);

Description

Sets the text of the bidirectional text object with directionality determined by the text itself. Use this for text that has been obtained from a resource file.

Parameters

const TDesC &aText

The text in logical order.

RRunInfoArray &aRunInfoArray

Return value

TInt

The number of characters that didn't fit in the available buffer.


SetText()

IMPORT_C TInt SetText(const TDesC &aText, TDirectionality aDirectionality, RRunInfoArray &aRunInfoArray);

Description

Sets the text of the bidirectional text with directionality determined by aDirectionality. Use this for text that has come from user input.

Parameters

const TDesC &aText

The text in logical order.

TDirectionality aDirectionality

Direction to use.

RRunInfoArray &aRunInfoArray

Return value

TInt

The number of characters that didn't fit in the available buffer.

Panic codes

Bidi

EBidiPanic_RunArrayNull The call to RRunInfoArray::OpenL() has not been made prior to this call to TBidiText::SetText()


SetTruncationChar()

IMPORT_C void SetTruncationChar(TChar aTruncateWith);

Description

Sets the character that will be added at the end of the text if the whole text cannot fit into the space specified.

Parameters

TChar aTruncateWith

The truncation char.


WrapText()

IMPORT_C void WrapText(TInt aWrappingWidth, const CFont &aFont, const MLineBreaker *aBreaker, TInt aMaxLines);

Description

Prepares the visually-ordered text according to the wrapping width and font specified. Text cannot be drawn until this has been done.

Parameters

TInt aWrappingWidth

The maximum width of the text in pixels. Note that this distance should be slightly less than the available width to allow for characters such as "W" which can have side-bearings that leak into the margins.

const CFont &aFont

The font that will provide the character metrics.

const MLineBreaker *aBreaker

An object for breaking the lines. May be NULL for default behaviour.

TInt aMaxLines

Number of lines to restrict wrapping to. The truncation character will be used if the text is too long for this number of lines. The number of lines wrapped to may not be greater than the figure passed to NewL.


WrapText()

IMPORT_C void WrapText(TInt aWrappingWidth, const CFont &aFont, const MLineBreaker *aBreaker=0);

Description

Prepares the visually-ordered text according to the wrapping width and font specified. Text cannot be drawn until this has been done.

Parameters

TInt aWrappingWidth

The maximum width of the text in pixels. Note that this distance should be slightly less than the available width to allow for characters such as "W" which can have side-bearings that leak into the margins.

const CFont &aFont

The font that will provide the character metrics.

const MLineBreaker *aBreaker

An object for breaking the lines. May be NULL for default behaviour.


MinimumSize()

IMPORT_C TSize MinimumSize(TInt aWrappingWidth, const CFont &aFont, TInt aLineGap, TInt aMaxLines=-1, const MLineBreaker *aBreaker=0) const;

Description

Calculate the minimum size needed to draw the current text, given the specified wrapping width, font, and line gap. Calling this method will not rewrap the object's text.

Parameters

TInt aWrappingWidth

The maximum width of the text in pixels. Note that this distance should be slightly less than the available width to allow for characters such as "W" which can have side-bearings that leak into the margins.

const CFont &aFont

The font that will provide the character metrics.

TInt aLineGap

The number of empty pixels between two lines of text. Note that this is not the same as the baseline spacing, which is the font height plus the line gap.

TInt aMaxLines

Number of lines to restrict wrapping to. The truncation character will be used if the text is too long for this number of lines. The number of lines wrapped to may be greater than the figure passed to NewL, and that figure will be used if the number of lines is specified as -1. If 0 (zero) is specified no limit is applied.

const MLineBreaker *aBreaker

An object for breaking the lines. May be NULL for default behaviour.

Return value

TSize


Text()

IMPORT_C TPtrC Text() const;

Description

Returns the original logically-ordered text supplied in the constructor.

Return value

TPtrC

The original logically-ordered text supplied in the constructor.


DisplayText()

IMPORT_C TPtrC DisplayText() const;

Description

Returns the text as prepared for display, provided that WrapText has been called. If WrapText has not been called, a panic will result.

Return value

TPtrC

The text as prepared for display


WrappingWidth()

IMPORT_C TInt WrappingWidth() const;

Description

Returns the wrapping width previously supplied to WrapText.

Return value

TInt

The wrapping.


Directionality()

IMPORT_C TDirectionality Directionality() const;

Description

Returns the directionality of the text.

Return value

TDirectionality

The directionality.


TruncationChar()

IMPORT_C TChar TruncationChar() const;

Description

Returns the truncation character used.

Return value

TChar

The truncation character.


NumberOfLinesInDisplayText()

IMPORT_C TInt NumberOfLinesInDisplayText() const;

Description

Reports the number of lines in the text to be drawn.

WrapText must have been called already.

Return value

TInt

The number of lines in the text which would be drawn by DrawText.


LineOfDisplayText()

IMPORT_C TPtrC LineOfDisplayText(TInt aLine, TInt &aWidthInPixels) const;

Description

Returns the text as prepared for display, provided that WrapText has been called. If WrapText has not been called, a panic will result.

Parameters

TInt aLine

Line number to retrieve.

TInt &aWidthInPixels

Return value

TPtrC

The text as prepared for display.


DrawText()

IMPORT_C void DrawText(CGraphicsContext &aGc, const TPoint &aLeft) const;

Description

Draws the first line of the text. WrapText must have been called already. Alignment is taken from the directionality of the text.

Parameters

CGraphicsContext &aGc

The graphics context to draw the text to. The graphics context's font is assumed to have been set to the same font that was passed to the previous call to WrapText.

const TPoint &aLeft

The left extreme of the baseline. Note that this should not be at the very edge of the available space, or characters such as "W" with left side bearings may be truncated.


DrawText()

IMPORT_C void DrawText(CGraphicsContext &aGc, const TPoint &aLeft, TInt aBaseLineSpacing, CGraphicsContext::TTextAlign aAlignment) const;

Description

Draws all of the text. WrapText must have been called already.

Parameters

CGraphicsContext &aGc

The graphics context to draw the text to. The graphics context's font is assumed to have been set to the same font that was passed to the previous call to WrapText.

const TPoint &aLeft

The left extreme of the baseline. Note that this should not be at the very edge of the available space, or characters such as "W" with left side bearings may be truncated.

TInt aBaseLineSpacing

The spacing between each line. If 0, only the first line is drawn.

CGraphicsContext::TTextAlign aAlignment

How to position the text horizontally.


DrawText()

IMPORT_C void DrawText(CGraphicsContext &aGc, const TPoint &aLeft, TInt aBaseLineSpacing) const;

Description

Draws all of the text. Alignment is taken from the directionality of the text. WrapText must have been called already.

Parameters

CGraphicsContext &aGc

The graphics context to draw the text to. The graphics context's font is assumed to have been set to the same font that was passed to the previous call to WrapText.

const TPoint &aLeft

The left extreme of the baseline. Note that this should not be at the very edge of the available space, or characters such as "W" with left side bearings may be truncated.

TInt aBaseLineSpacing

The spacing between each line. If 0, only the first line is drawn.

[Top]


Member enumerations


Enum TDirectionality

TDirectionality

Description

Overall directionality of the text.

ELeftToRight

Text reading begins on the left.

ERightToLeft

Text reading begins on the right.


Enum TPanicCodes

TPanicCodes

Description

Class specific panic codes

EPanicRunArrayNull