--- a/epoc32/include/mw/aknbiditextutils.h Tue Nov 24 13:55:44 2009 +0000
+++ b/epoc32/include/mw/aknbiditextutils.h Tue Mar 16 16:12:26 2010 +0000
@@ -1,1 +1,449 @@
-aknbiditextutils.h
+/*
+* Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies).
+* All rights reserved.
+* This component and the accompanying materials are made available
+* under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
+* which accompanies this distribution, and is available
+* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
+*
+* Initial Contributors:
+* Nokia Corporation - initial contribution.
+*
+* Contributors:
+*
+* Description: 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.
+*
+*
+*/
+
+
+
+#ifndef AKN_BIDI_TEXT_UTILS_H
+#define AKN_BIDI_TEXT_UTILS_H
+
+// INCLUDES
+#include <e32base.h>
+#include <uikon.hrh> // KEllipsis
+#include <gdi.h> // For CCFont::TMeasureTextInput::TFlags
+
+// CONSTANTS
+
+const TInt KAknBidiExtraSpacePerLine = 4;
+
+// FORWARD DECLARATIONS
+
+
+// CLASS DECLARATION
+
+/**
+* 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.
+*
+* @lib avkon.dll
+* @since 2.0
+*/
+class AknBidiTextUtils
+ {
+ public:
+
+ /**
+ * Overall paragraph directionality
+ */
+ enum TParagraphDirectionality
+ {
+ EImplicit = 0, // implicit directionality of input text
+ ELeftToRight = 1,
+ ERightToLeft = 2
+ };
+
+ public: // New functions
+
+ /**
+ * Generic text clipping. This method allocates memory for visual buffer,
+ * and can leave in OOM situations.
+ *
+ * @since 2.0
+ *
+ * @param 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.
+ *
+ * @param aFont Font used when drawing the text.
+ *
+ * @param aMaxWidthInPixels Maximum width of text that is not be clipped.
+ *
+ * @param 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.
+ *
+ * @param aDirectionality Paragraph directionality.
+ *
+ * @param aClipChar The truncation character.
+ * 0xFFFF if no truncation character is to be used.
+ *
+ * @return ETrue if the text was clipped, EFalse otherwise.
+ */
+ IMPORT_C static TBool ConvertToVisualAndClipL(
+ TDes& aLogicalText,
+ const CFont& aFont,
+ TInt aMaxWidthInPixels,
+ TInt aMaxClippedWidthInPixels,
+ AknBidiTextUtils::TParagraphDirectionality aDirectionality = EImplicit,
+ TChar aClipChar = KEllipsis );
+
+ /**
+ * 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
+ *
+ * @param aLogicalText String to be clipped in logical order.
+ *
+ * @param 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.
+ *
+ * @param aFont Font used when drawing the text.
+ *
+ * @param aMaxWidthInPixels Maximum width of text that is not clipped.
+ *
+ * @param 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.
+ *
+ * @param aDirectionality Paragraph directionality.
+ *
+ * @param aClipChar The truncation character.
+ * 0xFFFF if no truncation character is to be used.
+ *
+ * @return ETrue if the text was clipped, EFalse otherwise.
+ */
+ IMPORT_C static TBool ConvertToVisualAndClip(
+ const TDesC& aLogicalText,
+ TDes& aVisualText,
+ const CFont& aFont,
+ TInt aMaxWidthInPixels,
+ TInt aMaxClippedWidthInPixels,
+ AknBidiTextUtils::TParagraphDirectionality aDirectionality = EImplicit,
+ TChar aClipChar = KEllipsis );
+
+ /**
+ * 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
+ *
+ * @param aLogicalText Text in logical order.
+ *
+ * @return KErrNone or KErrNoMemory.
+ */
+ IMPORT_C static TInt PrepareRunInfoArray( const TDesC& aLogicalText );
+
+ /**
+ * 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
+ *
+ * @param 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.
+ *
+ * @param aLineWidthArray Line widths in pixels. Also determines maximum
+ * number of lines.
+ *
+ * @param aFont Used font.
+ *
+ * @param aWrappedArray Pointers to wrapped lines.
+ *
+ * @param aInsertTruncationChar Whether to insert truncation character
+ * (KEllipsis) or not if the text does not fit in
+ * given maximum number of lines.
+ *
+ * @param aDirectionality Paragraph directionality.
+ */
+ IMPORT_C static void ConvertToVisualAndWrapToArrayL(
+ TDes& aLogicalText,
+ const CArrayFix<TInt>& aLineWidthArray,
+ const CFont& aFont,
+ CArrayFix<TPtrC>& aWrappedArray,
+ TBool aInsertTruncationChar,
+ AknBidiTextUtils::TParagraphDirectionality aDirectionality = EImplicit );
+
+ /**
+ * 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
+ *
+ * @param 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().
+ *
+ * @param aLineWidth Constant line width in pixels.
+ *
+ * @param aFont Used font.
+ *
+ * @param aWrappedArray Pointers to wrapped lines.
+ *
+ * @param aDirectionality Paragraph directionality.
+ *
+ * @return Heap descriptor containing the wrapped string in visual form.
+ * Ownership is transferred to the caller.
+ */
+ IMPORT_C static HBufC* ConvertToVisualAndWrapToArrayL(
+ const TDesC& aLogicalText,
+ TInt aLineWidth,
+ const CFont& aFont,
+ CArrayFix<TPtrC>& aWrappedArray,
+ AknBidiTextUtils::TParagraphDirectionality aDirectionality = EImplicit );
+
+ /**
+ * 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
+ *
+ * @param 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.
+ *
+ * @param aLineWidthArray Line widths in pixels. Also determines maximum
+ * number of lines.
+ *
+ * @param aFont Used font.
+ *
+ * @param aChoppedArray Pointers to chopped lines.
+ *
+ * @param aDirectionality Paragraph directionality.
+ */
+ IMPORT_C static void ConvertToVisualAndChopToArrayL(
+ TDes& aLogicalText,
+ const CArrayFix<TInt>& aLineWidthArray,
+ const CFont& aFont,
+ CArrayFix<TPtrC>& aChoppedArray,
+ AknBidiTextUtils::TParagraphDirectionality aDirectionality = EImplicit );
+
+ /**
+ * 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
+ *
+ * @param 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().
+ *
+ * @param aLineWidth Constant line width in pixels
+ *
+ * @param aFont Used font.
+ *
+ * @param aChoppedArray Pointers to chopped lines.
+ *
+ * @param aDirectionality Paragraph directionality.
+ *
+ * @return Heap descriptor containing the chopped string in visual form.
+ * Ownership is transferred to the caller.
+ */
+ IMPORT_C static HBufC* ConvertToVisualAndChopToArrayL(
+ const TDesC& aLogicalText,
+ TInt aLineWidth,
+ const CFont& aFont,
+ CArrayFix<TPtrC>& aChoppedArray,
+ TParagraphDirectionality aDirectionality = EImplicit );
+
+ /**
+ * Converts a string in visual order and wraps it to lines by inserting
+ * '\n' after each line in text.
+ * The result is copied into aWrappedString.
+ *
+ * @since 2.0
+ *
+ * @param 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.
+ * '\n' is inserted after each line.
+ * These lines can then be renderered using e.g.
+ * CGraphicsContext::DrawText().
+ *
+ * @param aLineWidthArray Line widths in pixels. Also determines maximum
+ * number of lines.
+ *
+ * @param aFont Used font.
+ *
+ * @param aWrappedString Wrapped string. The maximum length of the descriptor
+ * must be at least
+ * ( aLogicalText.Length() +
+ * aLineWidthArray.Count() * (KAknBidiExtraSpacePerLine+1) ).
+ * Otherwise, a panic is raised.
+ *
+ * @param aInsertTruncationChar Whether to insert truncation character
+ * (KEllipsis) or not if the text does not fit in
+ * given maximum number of lines.
+ *
+ * @param aDirectionality Paragraph directionality.
+ */
+ IMPORT_C static void ConvertToVisualAndWrapToStringL(
+ const TDesC& aLogicalText,
+ const CArrayFix<TInt>& aLineWidthArray,
+ const CFont& aFont,
+ TDes& aWrappedString,
+ TBool aInsertTruncationChar,
+ AknBidiTextUtils::TParagraphDirectionality aDirectionality = EImplicit );
+
+ // -------------------------------------------------------------------------
+ // The following methods are introduced in release 2.1
+ // -------------------------------------------------------------------------
+
+ /**
+ * 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
+ *
+ * @param 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().
+ *
+ * @param 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.
+ *
+ * @param aFont Used font.
+ *
+ * @param aWrappedArray Pointers to wrapped lines.
+ *
+ * @param aDirectionality Paragraph directionality.
+ *
+ * @return Heap descriptor containing the wrapped string in visual form.
+ * Ownership is transferred to the caller.
+ */
+ IMPORT_C static HBufC* ConvertToVisualAndWrapToArrayWholeTextL(
+ const TDesC& aLogicalText,
+ const CArrayFix<TInt>& aLineWidthArray,
+ const CFont& aFont,
+ CArrayFix<TPtrC>& aWrappedArray,
+ AknBidiTextUtils::TParagraphDirectionality aDirectionality = EImplicit );
+
+ /**
+ * 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
+ * @param aFont Font to use
+ * @param aText Text to be measured
+ * @param aOrder Whether the text provided is in visual or logical order
+ * @return width of the text in pixels.
+ */
+ IMPORT_C static TInt AknBidiTextUtils::MeasureTextBoundsWidth(
+ const CFont& aFont,
+ const TDesC& aText,
+ CFont::TMeasureTextInput::TFlags aOrder);
+
+ private:
+
+ static TBool DoConvertToVisualAndClip(
+ const TDesC& aLogicalText,
+ TDes& aVisualText,
+ const CFont& aFont,
+ TInt aMaxWidthInPixels,
+ TInt aMaxClippedWidthInPixels,
+ AknBidiTextUtils::TParagraphDirectionality aDirectionality,
+ TChar aClipChar );
+
+ /**
+ * C++ default constructor.
+ */
+ AknBidiTextUtils();
+ };
+
+#endif // AKN_BIDI_TEXT_UTILS_H
+
+// End of File