/*

* 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