AknBidiTextUtils Class Reference

class AknBidiTextUtils

Text utilities e.g. truncating and wrapping to be used in code that needs to support text that requires conversion from logical to visual order, e.g. Arabic/Hebrew Logical text is given as input to all methods. Output text is in visual order.

Input text buffers given as parameters must contain extra space for some additional characters as stated in method descriptions.

avkon.dll
Since
2.0
Public Member Functions
IMPORT_C voidConvertToVisualAndChopToArrayL(TDes &, const CArrayFix< TInt > &, const CFont &, CArrayFix< TPtrC > &, AknBidiTextUtils::TParagraphDirectionality)
IMPORT_C HBufC *ConvertToVisualAndChopToArrayL(const TDesC &, TInt, const CFont &, CArrayFix< TPtrC > &, TParagraphDirectionality)
IMPORT_C TBoolConvertToVisualAndClip(const TDesC &, TDes &, const CFont &, TInt, TInt, AknBidiTextUtils::TParagraphDirectionality, TChar)
IMPORT_C TBoolConvertToVisualAndClipL(TDes &, const CFont &, TInt, TInt, AknBidiTextUtils::TParagraphDirectionality, TChar)
IMPORT_C voidConvertToVisualAndWrapToArrayL(TDes &, const CArrayFix< TInt > &, const CFont &, CArrayFix< TPtrC > &, TBool, AknBidiTextUtils::TParagraphDirectionality)
IMPORT_C HBufC *ConvertToVisualAndWrapToArrayL(const TDesC &, TInt, const CFont &, CArrayFix< TPtrC > &, AknBidiTextUtils::TParagraphDirectionality)
IMPORT_C HBufC *ConvertToVisualAndWrapToArrayWholeTextL(const TDesC &, const CArrayFix< TInt > &, const CFont &, CArrayFix< TPtrC > &, AknBidiTextUtils::TParagraphDirectionality)
IMPORT_C voidConvertToVisualAndWrapToStringL(const TDesC &, const CArrayFix< TInt > &, const CFont &, TDes &, TBool, AknBidiTextUtils::TParagraphDirectionality)
IMPORT_C TIntMeasureTextBoundsWidth(const CFont &, const TDesC &, CFont::TMeasureTextInput::TFlags)
IMPORT_C TIntPrepareRunInfoArray(const TDesC &)
Private Member Functions
AknBidiTextUtils()
TBool DoConvertToVisualAndClip(const TDesC &, TDes &, const CFont &, TInt, TInt, AknBidiTextUtils::TParagraphDirectionality, TChar)
Public Member Enumerations
enumTParagraphDirectionality { EImplicit = 0, ELeftToRight = 1, ERightToLeft = 2 }

Constructor & Destructor Documentation

AknBidiTextUtils()

AknBidiTextUtils()[private]

C++ default constructor.

Member Functions Documentation

ConvertToVisualAndChopToArrayL(TDes &, const CArrayFix< TInt > &, const CFont &, CArrayFix< TPtrC > &, AknBidiTextUtils::TParagraphDirectionality)

IMPORT_C voidConvertToVisualAndChopToArrayL(TDes &aLogicalText,
const CArrayFix< TInt > &aLineWidthArray,
const CFont &aFont,
CArrayFix< TPtrC > &aChoppedArray,
AknBidiTextUtils::TParagraphDirectionalityaDirectionality = EImplicit
)[static]

Converts a string in visual order and chops each line when a line break character is encountered. Clips at the end of each line if there isn't enough space on that line. When clipping, KEllipsis (shown as 3 dots) is inserted at the end of the line. The pointers in aChoppedArray are set to point to positions inside aLogicalText.

Since
2.0

Parameters

TDes & aLogicalTextLogical text to be chopped. This method converts it in visual form (in strictly left to right order) and chops each line when a line break character is encountered. These lines can then be renderered using e.g. CGraphicsContext::DrawText(). The descriptor must contain extra space of at least (aLineWidthArray.Count() * KAknBidiExtraSpacePerLine). Otherwise, a panic is raised.
const CArrayFix< TInt > & aLineWidthArrayLine widths in pixels. Also determines maximum number of lines.
const CFont & aFontUsed font.
CArrayFix< TPtrC > & aChoppedArrayPointers to chopped lines.
AknBidiTextUtils::TParagraphDirectionality aDirectionality = EImplicitParagraph directionality.

ConvertToVisualAndChopToArrayL(const TDesC &, TInt, const CFont &, CArrayFix< TPtrC > &, TParagraphDirectionality)

IMPORT_C HBufC *ConvertToVisualAndChopToArrayL(const TDesC &aLogicalText,
TIntaLineWidth,
const CFont &aFont,
CArrayFix< TPtrC > &aChoppedArray,
TParagraphDirectionalityaDirectionality = EImplicit
)[static]

Converts a string in visual order and chops each line when a line break character is encountered. Clips at the end of each line if there isn't enough space on that line. When clipping, KEllipsis (shown as 3 dots) is inserted at the end of the line. The pointers in aChoppedArray are set to point to positions inside the returned heap descriptor.

Since
2.0

Parameters

const TDesC & aLogicalTextLogical text to be chopped. This method converts it in visual form (in strictly left to right order) and chops each line when a line break character is encountered. (The returned heap descriptor contains the string in visual order.) These lines can then be renderered using e.g. CGraphicsContext::DrawText().
TInt aLineWidthConstant line width in pixels
const CFont & aFontUsed font.
CArrayFix< TPtrC > & aChoppedArrayPointers to chopped lines.
TParagraphDirectionality aDirectionality = EImplicitParagraph directionality.

ConvertToVisualAndClip(const TDesC &, TDes &, const CFont &, TInt, TInt, AknBidiTextUtils::TParagraphDirectionality, TChar)

IMPORT_C TBoolConvertToVisualAndClip(const TDesC &aLogicalText,
TDes &aVisualText,
const CFont &aFont,
TIntaMaxWidthInPixels,
TIntaMaxClippedWidthInPixels,
AknBidiTextUtils::TParagraphDirectionalityaDirectionality = EImplicit,
TCharaClipChar = KEllipsis
)[static]

Generic text clipping. This method does not allocate memory and can be used in non-leaving functions. You must give a preallocated visual buffer as a parameter.

Since
2.0

Parameters

const TDesC & aLogicalTextString to be clipped in logical order.
TDes & aVisualTextThe reordered text in visual form is returned here. This method converts aLogicalText into visual order and clips it if necessary. Maximum length of this descriptor must be at least aLogicalText.Length() + KAknBidiExtraSpacePerLine. otherwise a panic is raised.
const CFont & aFontFont used when drawing the text.
TInt aMaxWidthInPixelsMaximum width of text that is not clipped.
TInt aMaxClippedWidthInPixelsMaximum width of text that is clipped. Note that this should not be many pixels bigger than aMaxWidthInPixels because then truncation character could appear after fully fitting text.
AknBidiTextUtils::TParagraphDirectionality aDirectionality = EImplicitParagraph directionality.
TChar aClipChar = KEllipsisThe truncation character. 0xFFFF if no truncation character is to be used.

ConvertToVisualAndClipL(TDes &, const CFont &, TInt, TInt, AknBidiTextUtils::TParagraphDirectionality, TChar)

IMPORT_C TBoolConvertToVisualAndClipL(TDes &aLogicalText,
const CFont &aFont,
TIntaMaxWidthInPixels,
TIntaMaxClippedWidthInPixels,
AknBidiTextUtils::TParagraphDirectionalityaDirectionality = EImplicit,
TCharaClipChar = KEllipsis
)[static]

Generic text clipping. This method allocates memory for visual buffer, and can leave in OOM situations.

Since
2.0

Parameters

TDes & aLogicalTextString to be clipped in logical order. This method converts it in visual order and clips it if necessary. The descriptor must contain extra space of at least KAknBidiExtraSpacePerLine. Otherwise, a panic is raised.
const CFont & aFontFont used when drawing the text.
TInt aMaxWidthInPixelsMaximum width of text that is not be clipped.
TInt aMaxClippedWidthInPixelsMaximum width of text that is clipped. Note that this should not be many pixels bigger than aMaxWidthInPixels because then truncation character could appear after fully fitting text.
AknBidiTextUtils::TParagraphDirectionality aDirectionality = EImplicitParagraph directionality.
TChar aClipChar = KEllipsisThe truncation character. 0xFFFF if no truncation character is to be used.

ConvertToVisualAndWrapToArrayL(TDes &, const CArrayFix< TInt > &, const CFont &, CArrayFix< TPtrC > &, TBool, AknBidiTextUtils::TParagraphDirectionality)

IMPORT_C voidConvertToVisualAndWrapToArrayL(TDes &aLogicalText,
const CArrayFix< TInt > &aLineWidthArray,
const CFont &aFont,
CArrayFix< TPtrC > &aWrappedArray,
TBoolaInsertTruncationChar,
AknBidiTextUtils::TParagraphDirectionalityaDirectionality = EImplicit
)[static]

Converts a string in visual order and wraps it to an array of pointers. The maximum number of lines and line widths are specified in aLineWidthArray. The pointers in aWrappedArray are set to point to positions inside descriptor given in aLogicalText.

Since
2.0

Parameters

TDes & aLogicalTextLogical text to be wrapped. This method converts it in visual form (in strictly left to right order) and wraps it to lines. These lines can then be renderered using e.g. CGraphicsContext::DrawText(). The descriptor must contain extra space of at least (aLineWidthArray.Count() * KAknBidiExtraSpacePerLine). Otherwise, a panic is raised.
const CArrayFix< TInt > & aLineWidthArrayLine widths in pixels. Also determines maximum number of lines.
const CFont & aFontUsed font.
CArrayFix< TPtrC > & aWrappedArrayPointers to wrapped lines.
TBool aInsertTruncationCharWhether to insert truncation character (KEllipsis) or not if the text does not fit in given maximum number of lines.
AknBidiTextUtils::TParagraphDirectionality aDirectionality = EImplicitParagraph directionality.

ConvertToVisualAndWrapToArrayL(const TDesC &, TInt, const CFont &, CArrayFix< TPtrC > &, AknBidiTextUtils::TParagraphDirectionality)

IMPORT_C HBufC *ConvertToVisualAndWrapToArrayL(const TDesC &aLogicalText,
TIntaLineWidth,
const CFont &aFont,
CArrayFix< TPtrC > &aWrappedArray,
AknBidiTextUtils::TParagraphDirectionalityaDirectionality = EImplicit
)[static]

Converts a string in visual order and wraps it to an array of pointers. Constant line width is given. The pointers in aWrappedArray are set to point to positions inside the returned heap descriptor.

Since
2.0

Parameters

const TDesC & aLogicalTextLogical text to be wrapped. This method converts it in visual form (in strictly left to right order) and wraps it to lines. (The returned heap descriptor contains the string in visual order.) These lines can then be renderered using e.g. CGraphicsContext::DrawText().
TInt aLineWidthConstant line width in pixels.
const CFont & aFontUsed font.
CArrayFix< TPtrC > & aWrappedArrayPointers to wrapped lines.
AknBidiTextUtils::TParagraphDirectionality aDirectionality = EImplicitParagraph directionality.

ConvertToVisualAndWrapToArrayWholeTextL(const TDesC &, const CArrayFix< TInt > &, const CFont &, CArrayFix< TPtrC > &, AknBidiTextUtils::TParagraphDirectionality)

IMPORT_C HBufC *ConvertToVisualAndWrapToArrayWholeTextL(const TDesC &aLogicalText,
const CArrayFix< TInt > &aLineWidthArray,
const CFont &aFont,
CArrayFix< TPtrC > &aWrappedArray,
AknBidiTextUtils::TParagraphDirectionalityaDirectionality = EImplicit
)[static]

Converts a string in visual order and wraps it to an array of pointers. Line widths are specified in aLineWidthArray. If all the text does not fit in the amount of lines in aLineWidthArray, the last line width in the array is used for all the remaining lines. The pointers in aWrappedArray are set to point to positions inside the returned heap descriptor.

Since
2.1

Parameters

const TDesC & aLogicalTextLogical text to be wrapped. This method converts it in visual form (in strictly left to right order) and wraps it to lines. (The returned heap descriptor contains the string in visual order.) These lines can then be renderered using e.g. CGraphicsContext::DrawText().
const CArrayFix< TInt > & aLineWidthArrayLine widths in pixels. If the whole text does not fit in the number of lines specified in the array, the last width is used for the remaining lines.
const CFont & aFontUsed font.
CArrayFix< TPtrC > & aWrappedArrayPointers to wrapped lines.
AknBidiTextUtils::TParagraphDirectionality aDirectionality = EImplicitParagraph directionality.

ConvertToVisualAndWrapToStringL(const TDesC &, const CArrayFix< TInt > &, const CFont &, TDes &, TBool, AknBidiTextUtils::TParagraphDirectionality)

IMPORT_C voidConvertToVisualAndWrapToStringL(const TDesC &aLogicalText,
const CArrayFix< TInt > &aLineWidthArray,
const CFont &aFont,
TDes &aWrappedString,
TBoolaInsertTruncationChar,
AknBidiTextUtils::TParagraphDirectionalityaDirectionality = EImplicit
)[static]

Converts a string in visual order and wraps it to lines by inserting '' after each line in text. The result is copied into aWrappedString.

Since
2.0

Parameters

const TDesC & aLogicalTextLogical text to be wrapped. This method converts it in visual form (in strictly left to right order) and wraps it to lines in aWrappedString. '' is inserted after each line. These lines can then be renderered using e.g. CGraphicsContext::DrawText().
const CArrayFix< TInt > & aLineWidthArrayLine widths in pixels. Also determines maximum number of lines.
const CFont & aFontUsed font.
TDes & aWrappedStringWrapped string. The maximum length of the descriptor must be at least ( aLogicalText.Length() + aLineWidthArray.Count() * (KAknBidiExtraSpacePerLine+1) ). Otherwise, a panic is raised.
TBool aInsertTruncationCharWhether to insert truncation character (KEllipsis) or not if the text does not fit in given maximum number of lines.
AknBidiTextUtils::TParagraphDirectionality aDirectionality = EImplicitParagraph directionality.

DoConvertToVisualAndClip(const TDesC &, TDes &, const CFont &, TInt, TInt, AknBidiTextUtils::TParagraphDirectionality, TChar)

TBool DoConvertToVisualAndClip(const TDesC &aLogicalText,
TDes &aVisualText,
const CFont &aFont,
TIntaMaxWidthInPixels,
TIntaMaxClippedWidthInPixels,
AknBidiTextUtils::TParagraphDirectionalityaDirectionality,
TCharaClipChar
)[private, static]

Parameters

const TDesC & aLogicalText
TDes & aVisualText
const CFont & aFont
TInt aMaxWidthInPixels
TInt aMaxClippedWidthInPixels
AknBidiTextUtils::TParagraphDirectionality aDirectionality
TChar aClipChar

MeasureTextBoundsWidth(const CFont &, const TDesC &, CFont::TMeasureTextInput::TFlags)

IMPORT_C TIntMeasureTextBoundsWidth(const CFont &aFont,
const TDesC &aText,
CFont::TMeasureTextInput::TFlagsaOrder
)[static]

Measures the full horizontal width in pixels of the passed-in text using a particular font, including in the width any side-bearings of the glyphs at the ends of the text, and any declared "advance" of the run of glyphs.

It cannot be used for vertical text measurement.

Side-bearings are parts of glyphs that extend left or right from the normal width or "advance" of the glyph. A left side-bearing, for instance, will overlap with a glyph to its left. Another way of thinking about this is that the origin (0,0) of the glyph is not at its bottom left.

The advance of a run of glyphs is the sum of the advances - once in visual ordering and shaping has been performed - of all the glyphs. It is defined relative to a drawing origin.

Within runs of text, side-bearings do not contribute to the width of the text. However, at the (visual) ends of text, they are likely to need to be counted, depending upon the exact use case.

This method returns the width of the horizontal envelope of the text by taking the extreme horizontal extents of the text bounds rectangle (which includes side-bearings on either end) and the extent of the advance. Thus it returns the width of : Min(<left_text_bound>, 0), Max( <right_text_bound>, <advance>)

This method should be used when the proposed text is going to be drawn using any horizontal CGraphicsContext::DrawText drawing API.

The text can be in visual or logical order.

Since
3.1

Parameters

const CFont & aFontFont to use
const TDesC & aTextText to be measured
CFont::TMeasureTextInput::TFlags aOrderWhether the text provided is in visual or logical order

PrepareRunInfoArray(const TDesC &)

IMPORT_C TIntPrepareRunInfoArray(const TDesC &aLogicalText)[static]

Tests how big run info array the given text requires and tries to increase the size of the array if required (stored in CAknEnv).

This method is useful with the non-leaving version of ConvertToVisualAndClip(). By calling this method successfully (means KErrNone is returned) at any point during the lifetime of the application it is guaranteed that the text gets correctly converted in visual form even in out-of-memory situation when calling ConvertToVisualAndClip().

Note that there is no use calling this method if you do not handle the return code, because the truncating methods already do that.

Since
2.0

Parameters

const TDesC & aLogicalTextText in logical order.

Member Enumerations Documentation

Enum TParagraphDirectionality

Overall paragraph directionality

Enumerators

EImplicit = 0
ELeftToRight = 1
ERightToLeft = 2