AknBidiTextUtils Class Reference

Public Types

Static Public Member Functions

Overall paragraph directionality.

Enumerator:

EImplicit
ELeftToRight
ERightToLeft

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.

Parameters:

	aLogicalText	Logical 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().
	aLineWidth	Constant line width in pixels
	aFont	Used font.
	aChoppedArray	Pointers to chopped lines.
	aDirectionality	Paragraph directionality.

Returns:

Heap descriptor containing the chopped string in visual form. Ownership is transferred to the caller.

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.

Parameters:

	aLogicalText	Logical 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.
	aLineWidthArray	Line widths in pixels. Also determines maximum number of lines.
	aFont	Used font.
	aChoppedArray	Pointers to chopped lines.
	aDirectionality	Paragraph directionality.

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.

Parameters:

	aLogicalText	String to be clipped in logical order.
	aVisualText	The 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.
	aFont	Font used when drawing the text.
	aMaxWidthInPixels	Maximum width of text that is not clipped.
	aMaxClippedWidthInPixels	Maximum 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.
	aDirectionality	Paragraph directionality.
	aClipChar	The truncation character. 0xFFFF if no truncation character is to be used.

Returns:

ETrue if the text was clipped, EFalse otherwise.

Generic text clipping.

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

Parameters:

	aLogicalText	String 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.
	aFont	Font used when drawing the text.
	aMaxWidthInPixels	Maximum width of text that is not be clipped.
	aMaxClippedWidthInPixels	Maximum 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.
	aDirectionality	Paragraph directionality.
	aClipChar	The truncation character. 0xFFFF if no truncation character is to be used.

Returns:

ETrue if the text was clipped, EFalse otherwise.

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.

Parameters:

	aLogicalText	Logical 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().
	aLineWidth	Constant line width in pixels.
	aFont	Used font.
	aWrappedArray	Pointers to wrapped lines.
	aDirectionality	Paragraph directionality.

Returns:

Heap descriptor containing the wrapped string in visual form. Ownership is transferred to the caller.

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.

Parameters:

	aLogicalText	Logical 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.
	aLineWidthArray	Line widths in pixels. Also determines maximum number of lines.
	aFont	Used font.
	aWrappedArray	Pointers to wrapped lines.
	aInsertTruncationChar	Whether to insert truncation character (KEllipsis) or not if the text does not fit in given maximum number of lines.
	aDirectionality	Paragraph directionality.

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.

Parameters:

	aLogicalText	Logical 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().
	aLineWidthArray	Line 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.
	aFont	Used font.
	aWrappedArray	Pointers to wrapped lines.
	aDirectionality	Paragraph directionality.

Returns:

Heap descriptor containing the wrapped string in visual form. Ownership is transferred to the caller.

Converts a string in visual order and wraps it to lines by inserting '
' after each line in text.

The result is copied into aWrappedString.

Parameters:

	aLogicalText	Logical 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().
	aLineWidthArray	Line widths in pixels. Also determines maximum number of lines.
	aFont	Used font.
	aWrappedString	Wrapped string. The maximum length of the descriptor must be at least ( aLogicalText.Length() + aLineWidthArray.Count() * (KAknBidiExtraSpacePerLine+1) ). Otherwise, a panic is raised.
	aInsertTruncationChar	Whether to insert truncation character (KEllipsis) or not if the text does not fit in given maximum number of lines.
	aDirectionality	Paragraph directionality.

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.

Parameters:

	aFont	Font to use
	aText	Text to be measured
	aOrder	Whether the text provided is in visual or logical order

Returns:

width of the text in pixels.

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.

Parameters:

aLogicalText

Text in logical order.

Returns:

KErrNone or KErrNoMemory.