williamr@2: /* williamr@2: * Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies). williamr@2: * All rights reserved. williamr@2: * This component and the accompanying materials are made available williamr@2: * 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 williamr@2: * which accompanies this distribution, and is available williamr@2: * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". williamr@2: * williamr@2: * Initial Contributors: williamr@2: * Nokia Corporation - initial contribution. williamr@2: * williamr@2: * Contributors: williamr@2: * williamr@2: * Description: Text utilities e.g. truncating and wrapping to be used in code williamr@2: * that needs to support text that requires conversion from logical williamr@2: * to visual order, e.g. Arabic/Hebrew. williamr@2: * Logical text is given as input to all methods. williamr@2: * Output text is in visual order. williamr@2: * williamr@2: * williamr@2: */ williamr@2: williamr@2: williamr@2: williamr@2: #ifndef AKN_BIDI_TEXT_UTILS_H williamr@2: #define AKN_BIDI_TEXT_UTILS_H williamr@2: williamr@2: // INCLUDES williamr@2: #include williamr@2: #include // KEllipsis williamr@2: #include // For CCFont::TMeasureTextInput::TFlags williamr@2: williamr@2: // CONSTANTS williamr@2: williamr@2: const TInt KAknBidiExtraSpacePerLine = 4; williamr@2: williamr@2: // FORWARD DECLARATIONS williamr@2: williamr@2: williamr@2: // CLASS DECLARATION williamr@2: williamr@2: /** williamr@2: * Text utilities e.g. truncating and wrapping to be used in code that needs to williamr@2: * support text that requires conversion from logical to visual order, williamr@2: * e.g. Arabic/Hebrew Logical text is given as input to all williamr@2: * methods. Output text is in visual order. williamr@2: * williamr@2: * Input text buffers given as parameters must contain extra space for some additional williamr@2: * characters as stated in method descriptions. williamr@2: * williamr@2: * @lib avkon.dll williamr@2: * @since 2.0 williamr@2: */ williamr@2: class AknBidiTextUtils williamr@2: { williamr@2: public: williamr@2: williamr@2: /** williamr@2: * Overall paragraph directionality williamr@2: */ williamr@2: enum TParagraphDirectionality williamr@2: { williamr@2: EImplicit = 0, // implicit directionality of input text williamr@2: ELeftToRight = 1, williamr@2: ERightToLeft = 2 williamr@2: }; williamr@2: williamr@2: public: // New functions williamr@2: williamr@2: /** williamr@2: * Generic text clipping. This method allocates memory for visual buffer, williamr@2: * and can leave in OOM situations. williamr@2: * williamr@2: * @since 2.0 williamr@2: * williamr@2: * @param aLogicalText String to be clipped in logical order. This method williamr@2: * converts it in visual order and clips it if necessary. williamr@2: * The descriptor must contain extra space of at least williamr@2: * KAknBidiExtraSpacePerLine. Otherwise, a panic is raised. williamr@2: * williamr@2: * @param aFont Font used when drawing the text. williamr@2: * williamr@2: * @param aMaxWidthInPixels Maximum width of text that is not be clipped. williamr@2: * williamr@2: * @param aMaxClippedWidthInPixels Maximum width of text that is clipped. williamr@2: * Note that this should not be many pixels bigger than aMaxWidthInPixels williamr@2: * because then truncation character could appear after fully fitting text. williamr@2: * williamr@2: * @param aDirectionality Paragraph directionality. williamr@2: * williamr@2: * @param aClipChar The truncation character. williamr@2: * 0xFFFF if no truncation character is to be used. williamr@2: * williamr@2: * @return ETrue if the text was clipped, EFalse otherwise. williamr@2: */ williamr@2: IMPORT_C static TBool ConvertToVisualAndClipL( williamr@2: TDes& aLogicalText, williamr@2: const CFont& aFont, williamr@2: TInt aMaxWidthInPixels, williamr@2: TInt aMaxClippedWidthInPixels, williamr@2: AknBidiTextUtils::TParagraphDirectionality aDirectionality = EImplicit, williamr@2: TChar aClipChar = KEllipsis ); williamr@2: williamr@2: /** williamr@2: * Generic text clipping. This method does not allocate memory and can williamr@2: * be used in non-leaving functions. You must give a preallocated visual williamr@2: * buffer as a parameter. williamr@2: * williamr@2: * @since 2.0 williamr@2: * williamr@2: * @param aLogicalText String to be clipped in logical order. williamr@2: * williamr@2: * @param aVisualText The reordered text in visual form is returned here. williamr@2: * This method converts aLogicalText into visual order williamr@2: * and clips it if necessary. Maximum length of this williamr@2: * descriptor must be at least williamr@2: * aLogicalText.Length() + KAknBidiExtraSpacePerLine. williamr@2: * otherwise a panic is raised. williamr@2: * williamr@2: * @param aFont Font used when drawing the text. williamr@2: * williamr@2: * @param aMaxWidthInPixels Maximum width of text that is not clipped. williamr@2: * williamr@2: * @param aMaxClippedWidthInPixels Maximum width of text that is clipped. williamr@2: * Note that this should not be many pixels bigger than aMaxWidthInPixels williamr@2: * because then truncation character could appear after fully fitting text. williamr@2: * williamr@2: * @param aDirectionality Paragraph directionality. williamr@2: * williamr@2: * @param aClipChar The truncation character. williamr@2: * 0xFFFF if no truncation character is to be used. williamr@2: * williamr@2: * @return ETrue if the text was clipped, EFalse otherwise. williamr@2: */ williamr@2: IMPORT_C static TBool ConvertToVisualAndClip( williamr@2: const TDesC& aLogicalText, williamr@2: TDes& aVisualText, williamr@2: const CFont& aFont, williamr@2: TInt aMaxWidthInPixels, williamr@2: TInt aMaxClippedWidthInPixels, williamr@2: AknBidiTextUtils::TParagraphDirectionality aDirectionality = EImplicit, williamr@2: TChar aClipChar = KEllipsis ); williamr@2: williamr@2: /** williamr@2: * Tests how big run info array the given text requires and williamr@2: * tries to increase the size of the array if required (stored in CAknEnv). williamr@2: * williamr@2: * This method is useful with the non-leaving version of williamr@2: * ConvertToVisualAndClip(). By calling this method successfully williamr@2: * (means KErrNone is returned) at any point during the lifetime of the application williamr@2: * it is guaranteed that the text gets correctly converted in visual form even williamr@2: * in out-of-memory situation when calling ConvertToVisualAndClip(). williamr@2: * williamr@2: * Note that there is no use calling this method if you do not handle the williamr@2: * return code, because the truncating methods already do that. williamr@2: * williamr@2: * @since 2.0 williamr@2: * williamr@2: * @param aLogicalText Text in logical order. williamr@2: * williamr@2: * @return KErrNone or KErrNoMemory. williamr@2: */ williamr@2: IMPORT_C static TInt PrepareRunInfoArray( const TDesC& aLogicalText ); williamr@2: williamr@2: /** williamr@2: * Converts a string in visual order and wraps it to an array of pointers. williamr@2: * The maximum number of lines and line widths are specified in williamr@2: * aLineWidthArray. The pointers in aWrappedArray are set to point to williamr@2: * positions inside descriptor given in aLogicalText. williamr@2: * williamr@2: * @since 2.0 williamr@2: * williamr@2: * @param aLogicalText Logical text to be wrapped. This method williamr@2: * converts it in visual form (in strictly left to williamr@2: * right order) and wraps it to lines. williamr@2: * These lines can then be renderered using e.g. williamr@2: * CGraphicsContext::DrawText(). williamr@2: * The descriptor must contain extra space of at least williamr@2: * (aLineWidthArray.Count() * KAknBidiExtraSpacePerLine). williamr@2: * Otherwise, a panic is raised. williamr@2: * williamr@2: * @param aLineWidthArray Line widths in pixels. Also determines maximum williamr@2: * number of lines. williamr@2: * williamr@2: * @param aFont Used font. williamr@2: * williamr@2: * @param aWrappedArray Pointers to wrapped lines. williamr@2: * williamr@2: * @param aInsertTruncationChar Whether to insert truncation character williamr@2: * (KEllipsis) or not if the text does not fit in williamr@2: * given maximum number of lines. williamr@2: * williamr@2: * @param aDirectionality Paragraph directionality. williamr@2: */ williamr@2: IMPORT_C static void ConvertToVisualAndWrapToArrayL( williamr@2: TDes& aLogicalText, williamr@2: const CArrayFix& aLineWidthArray, williamr@2: const CFont& aFont, williamr@2: CArrayFix& aWrappedArray, williamr@2: TBool aInsertTruncationChar, williamr@2: AknBidiTextUtils::TParagraphDirectionality aDirectionality = EImplicit ); williamr@2: williamr@2: /** williamr@2: * Converts a string in visual order and wraps it to an array of pointers. williamr@2: * Constant line width is given. The pointers in aWrappedArray are set to williamr@2: * point to positions inside the returned heap descriptor. williamr@2: * williamr@2: * @since 2.0 williamr@2: * williamr@2: * @param aLogicalText Logical text to be wrapped. This method williamr@2: * converts it in visual form (in strictly left to williamr@2: * right order) and wraps it to lines. (The returned williamr@2: * heap descriptor contains the string in visual williamr@2: * order.) williamr@2: * These lines can then be renderered using e.g. williamr@2: * CGraphicsContext::DrawText(). williamr@2: * williamr@2: * @param aLineWidth Constant line width in pixels. williamr@2: * williamr@2: * @param aFont Used font. williamr@2: * williamr@2: * @param aWrappedArray Pointers to wrapped lines. williamr@2: * williamr@2: * @param aDirectionality Paragraph directionality. williamr@2: * williamr@2: * @return Heap descriptor containing the wrapped string in visual form. williamr@2: * Ownership is transferred to the caller. williamr@2: */ williamr@2: IMPORT_C static HBufC* ConvertToVisualAndWrapToArrayL( williamr@2: const TDesC& aLogicalText, williamr@2: TInt aLineWidth, williamr@2: const CFont& aFont, williamr@2: CArrayFix& aWrappedArray, williamr@2: AknBidiTextUtils::TParagraphDirectionality aDirectionality = EImplicit ); williamr@2: williamr@2: /** williamr@2: * Converts a string in visual order and chops each line when a line break williamr@2: * character is encountered. williamr@2: * Clips at the end of each line if there isn't enough space williamr@2: * on that line. When clipping, KEllipsis (shown as 3 dots) is inserted at williamr@2: * the end of the line. The pointers in aChoppedArray are set to point to williamr@2: * positions inside aLogicalText. williamr@2: * williamr@2: * @since 2.0 williamr@2: * williamr@2: * @param aLogicalText Logical text to be chopped. This method williamr@2: * converts it in visual form (in strictly left to williamr@2: * right order) and chops each line when a line break williamr@2: * character is encountered. williamr@2: * These lines can then be renderered using e.g. williamr@2: * CGraphicsContext::DrawText(). williamr@2: * The descriptor must contain extra space of at least williamr@2: * (aLineWidthArray.Count() * KAknBidiExtraSpacePerLine). williamr@2: * Otherwise, a panic is raised. williamr@2: * williamr@2: * @param aLineWidthArray Line widths in pixels. Also determines maximum williamr@2: * number of lines. williamr@2: * williamr@2: * @param aFont Used font. williamr@2: * williamr@2: * @param aChoppedArray Pointers to chopped lines. williamr@2: * williamr@2: * @param aDirectionality Paragraph directionality. williamr@2: */ williamr@2: IMPORT_C static void ConvertToVisualAndChopToArrayL( williamr@2: TDes& aLogicalText, williamr@2: const CArrayFix& aLineWidthArray, williamr@2: const CFont& aFont, williamr@2: CArrayFix& aChoppedArray, williamr@2: AknBidiTextUtils::TParagraphDirectionality aDirectionality = EImplicit ); williamr@2: williamr@2: /** williamr@2: * Converts a string in visual order and chops each line when a line break williamr@2: * character is encountered. williamr@2: * Clips at the end of each line if there isn't enough space williamr@2: * on that line. When clipping, KEllipsis (shown as 3 dots) is inserted at williamr@2: * the end of the line. The pointers in aChoppedArray are set to point to williamr@2: * positions inside the returned heap descriptor. williamr@2: * williamr@2: * @since 2.0 williamr@2: * williamr@2: * @param aLogicalText Logical text to be chopped. This method williamr@2: * converts it in visual form (in strictly left to williamr@2: * right order) and chops each line when a line break williamr@2: * character is encountered. (The returned williamr@2: * heap descriptor contains the string in visual williamr@2: * order.) williamr@2: * These lines can then be renderered using e.g. williamr@2: * CGraphicsContext::DrawText(). williamr@2: * williamr@2: * @param aLineWidth Constant line width in pixels williamr@2: * williamr@2: * @param aFont Used font. williamr@2: * williamr@2: * @param aChoppedArray Pointers to chopped lines. williamr@2: * williamr@2: * @param aDirectionality Paragraph directionality. williamr@2: * williamr@2: * @return Heap descriptor containing the chopped string in visual form. williamr@2: * Ownership is transferred to the caller. williamr@2: */ williamr@2: IMPORT_C static HBufC* ConvertToVisualAndChopToArrayL( williamr@2: const TDesC& aLogicalText, williamr@2: TInt aLineWidth, williamr@2: const CFont& aFont, williamr@2: CArrayFix& aChoppedArray, williamr@2: TParagraphDirectionality aDirectionality = EImplicit ); williamr@2: williamr@2: /** williamr@2: * Converts a string in visual order and wraps it to lines by inserting williamr@2: * '\n' after each line in text. williamr@2: * The result is copied into aWrappedString. williamr@2: * williamr@2: * @since 2.0 williamr@2: * williamr@2: * @param aLogicalText Logical text to be wrapped. This method williamr@2: * converts it in visual form (in strictly left to williamr@2: * right order) and wraps it to lines in aWrappedString. williamr@2: * '\n' is inserted after each line. williamr@2: * These lines can then be renderered using e.g. williamr@2: * CGraphicsContext::DrawText(). williamr@2: * williamr@2: * @param aLineWidthArray Line widths in pixels. Also determines maximum williamr@2: * number of lines. williamr@2: * williamr@2: * @param aFont Used font. williamr@2: * williamr@2: * @param aWrappedString Wrapped string. The maximum length of the descriptor williamr@2: * must be at least williamr@2: * ( aLogicalText.Length() + williamr@2: * aLineWidthArray.Count() * (KAknBidiExtraSpacePerLine+1) ). williamr@2: * Otherwise, a panic is raised. williamr@2: * williamr@2: * @param aInsertTruncationChar Whether to insert truncation character williamr@2: * (KEllipsis) or not if the text does not fit in williamr@2: * given maximum number of lines. williamr@2: * williamr@2: * @param aDirectionality Paragraph directionality. williamr@2: */ williamr@2: IMPORT_C static void ConvertToVisualAndWrapToStringL( williamr@2: const TDesC& aLogicalText, williamr@2: const CArrayFix& aLineWidthArray, williamr@2: const CFont& aFont, williamr@2: TDes& aWrappedString, williamr@2: TBool aInsertTruncationChar, williamr@2: AknBidiTextUtils::TParagraphDirectionality aDirectionality = EImplicit ); williamr@2: williamr@2: // ------------------------------------------------------------------------- williamr@2: // The following methods are introduced in release 2.1 williamr@2: // ------------------------------------------------------------------------- williamr@2: williamr@2: /** williamr@2: * Converts a string in visual order and wraps it to an array of pointers. williamr@2: * Line widths are specified in aLineWidthArray. If all the text does not fit williamr@2: * in the amount of lines in aLineWidthArray, the last line width in the array williamr@2: * is used for all the remaining lines. The pointers in aWrappedArray are set williamr@2: * to point to positions inside the returned heap descriptor. williamr@2: * williamr@2: * @since 2.1 williamr@2: * williamr@2: * @param aLogicalText Logical text to be wrapped. This method williamr@2: * converts it in visual form (in strictly left to williamr@2: * right order) and wraps it to lines. (The returned williamr@2: * heap descriptor contains the string in visual williamr@2: * order.) williamr@2: * These lines can then be renderered using e.g. williamr@2: * CGraphicsContext::DrawText(). williamr@2: * williamr@2: * @param aLineWidthArray Line widths in pixels. If the whole text does williamr@2: * not fit in the number of lines specified in the williamr@2: * array, the last width is used for the remaining williamr@2: * lines. williamr@2: * williamr@2: * @param aFont Used font. williamr@2: * williamr@2: * @param aWrappedArray Pointers to wrapped lines. williamr@2: * williamr@2: * @param aDirectionality Paragraph directionality. williamr@2: * williamr@2: * @return Heap descriptor containing the wrapped string in visual form. williamr@2: * Ownership is transferred to the caller. williamr@2: */ williamr@2: IMPORT_C static HBufC* ConvertToVisualAndWrapToArrayWholeTextL( williamr@2: const TDesC& aLogicalText, williamr@2: const CArrayFix& aLineWidthArray, williamr@2: const CFont& aFont, williamr@2: CArrayFix& aWrappedArray, williamr@2: AknBidiTextUtils::TParagraphDirectionality aDirectionality = EImplicit ); williamr@2: williamr@2: /** williamr@2: * Measures the full horizontal width in pixels of the passed-in text using a particular font, williamr@2: * including in the width any side-bearings of the glyphs at the ends of the text, and any williamr@2: * declared "advance" of the run of glyphs. williamr@2: * williamr@2: * It cannot be used for vertical text measurement. williamr@2: * williamr@2: * Side-bearings are parts of glyphs that extend left or right from the normal width williamr@2: * or "advance" of the glyph. A left side-bearing, for instance, will overlap with a glyph williamr@2: * to its left. Another way of thinking about this is that the origin (0,0) of the glyph is williamr@2: * not at its bottom left. williamr@2: * williamr@2: * The advance of a run of glyphs is the sum of the advances - once in visual ordering and williamr@2: * shaping has been performed - of all the glyphs. It is defined relative to a drawing origin. williamr@2: * williamr@2: * Within runs of text, side-bearings do not contribute to the width of the text. However, williamr@2: * at the (visual) ends of text, they are likely to need to be counted, depending upon the williamr@2: * exact use case. williamr@2: * williamr@2: * This method returns the width of the horizontal envelope of the text by taking the extreme williamr@2: * horizontal extents of the text bounds rectangle (which includes side-bearings on either end) williamr@2: * and the extent of the advance. Thus it returns the width of : williamr@2: * Min(, 0), Max( , ) williamr@2: * williamr@2: * This method should be used when the proposed text is going to be drawn using any horizontal williamr@2: * CGraphicsContext::DrawText drawing API. williamr@2: * williamr@2: * The text can be in visual or logical order. williamr@2: * williamr@2: * @since 3.1 williamr@2: * @param aFont Font to use williamr@2: * @param aText Text to be measured williamr@2: * @param aOrder Whether the text provided is in visual or logical order williamr@2: * @return width of the text in pixels. williamr@2: */ williamr@2: IMPORT_C static TInt AknBidiTextUtils::MeasureTextBoundsWidth( williamr@2: const CFont& aFont, williamr@2: const TDesC& aText, williamr@2: CFont::TMeasureTextInput::TFlags aOrder); williamr@2: williamr@2: private: williamr@2: williamr@2: static TBool DoConvertToVisualAndClip( williamr@2: const TDesC& aLogicalText, williamr@2: TDes& aVisualText, williamr@2: const CFont& aFont, williamr@2: TInt aMaxWidthInPixels, williamr@2: TInt aMaxClippedWidthInPixels, williamr@2: AknBidiTextUtils::TParagraphDirectionality aDirectionality, williamr@2: TChar aClipChar ); williamr@2: williamr@2: /** williamr@2: * C++ default constructor. williamr@2: */ williamr@2: AknBidiTextUtils(); williamr@2: }; williamr@2: williamr@2: #endif // AKN_BIDI_TEXT_UTILS_H williamr@2: williamr@2: // End of File