/*

* Copyright (c) 2002-2007 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description: 

*     General Avkon Utilities. Includes:

*       - listbox utilities

*       - layout utilities

* 

*

*/

#ifndef __AKNUTILS_H__

#define __AKNUTILS_H__

#include <eiktxlbm.h>

#include <avkon.hrh>

#include <avkon.rsg>

#include <coedef.h>

#include <coecobs.h>

#include <w32std.h>

#include <gulalign.h>

#include <gulutil.h>

#include <eikenv.h>

#include <biditext.h>

#include <eiksbfrm.h>

#include <AknsConstants.h>

#include <aknenv.h>

#include <AknLayout.lag>

// These are for listbox column lengths (These are used to allocate memory from stack while drawing listboxes, they should be as small as possible, but not smaller!)

const TInt KMaxColumnDataLength = 80; // This is maximum length of data for one listbox column -- after that the data is truncated before drawing.

const TInt KMaxTotalDataLength = 8*KMaxColumnDataLength;  // max of 5 columns can have full 80 characters...

/** AVKON utility module

 *

 * From this file, you can find several tools for making application development easier for S60

 *

 * 1) Conversion modules to convert coordinate data from european LAF to usable formats

 *     AknLayoutUtils, TAknLayoutRect, TAknLayoutText

 * 2) Utilities to clip text

 * 3) Part of selection service implementation

 * 4) Different classes that help using listboxes

 * 5) Handling colors in AKN_LAF_COLOR macro.

 * 6) Resource readers for different purposes

 * 7) Utility to find files without specifying the drive letter or path

 */

class CCoeControl;

class CEikTextListBox;

class CEikColumnListBox;

class CEikFormattedCellListBox;

class CGulIcon;

class CEikSettingsListBox;

class CAknLAF;

class CEikImage;

class CEikMfne;

class CEikListBox;

class CEikLabel;

class CEikEdwin;

class CEikMenuPane;

class CAknPopupField;

class CListBoxView;

class CAknColumnListBox;

class CEikSecretEditor;

class CFindExtension;

class CAknLayoutFont;

class TAknFontSpecification;

class CAknAppUiBase;

class TAknWindowLineLayout;

class TAknMultiLineTextLayout;

class TAknTextLineLayout;

/**

 * Egul library had methods to clip text from right side, this class includes methods to clip from both sides.

 * It does add 3 dots to the end of the text.

 */

const TInt  KDefaultClipWidth = -1;

const TUint KDefaultClipChar  = TUint(0x2026);

// Constant to use in AknLayoutUtils to indicate that the parameter is not to be used as a override value

const TInt KAknLayoutUtilsDoNotOverride = -1;

/**

* Text utilities.

* Text truncating and wrapping methods in this class do not support 

* text that requires conversion from logical to visual form,

* e.g. Arabic/Hebrew, Thai and Hindi text. Code that needs to support that

* kind of text should use corresponding methods in AknBidiTextUtils instead.

*/

class AknTextUtils 

    {

public:

    enum TClipDirection

    {

    EDoNotClip,

    EClipFromEnd,

    EClipFromBeginning

    };

    /** ClipToFit() Generic clipping

    @param aBuffer         String that needs to be clipped. will be modified by this call

    @param aFont           Font used in the code

    @param aMaxWidthInPixels Maximum length of text that will not be clipped.

    @param aDir            Where is the text clipped from. EDoNotClip, EClipFromEnd, EClipFromBeginning.

    @param aClipWidth      The length of the text after clipping. KDefaultClipWidth will make it use aMaxWidthInPixels.

    @param aClipString     The representation of three dots. (not really used anywhere - use the default value always or "")

    returns true if the text was clipped and 3 dots were added. 

    */

    IMPORT_C static TBool ClipToFit(TDes& aBuffer,

                                    const CFont& aFont, 

                                    TInt aMaxWidthInPixels,

                                    TClipDirection aDir=EClipFromEnd,

                                    TInt aClipWidth = KDefaultClipWidth,

                                    const TDesC &aClipString=_L("..."));

    /** ClipToFit() for clipping text inside lists

     *

     * NOTICE: This method cannot handle situation where the text may dynamically change its size! Especially when you have bitmaps on the right side!

     *

     * This needs to be done AFTER the listbox has done its SizeChanged()!

     */

    IMPORT_C static TBool ClipToFit(TDes& aBuffer, 

                                    TClipDirection aDir,

                                    CEikFormattedCellListBox *aListBox,

                                    TInt aItemIndex,

                                    TInt aSubCellNumber);

    /** ClipToFit() for clipping text inside lists

     *

     * NOTICE: This method cannot handle situation where the text may dynamically change its size! Especially when you have bitmaps on the right side!

     *

     * This needs to be done AFTER the listbox has done its SizeChanged()!

     */

    IMPORT_C static TBool ClipToFit(TDes& aBuffer,

                                    TClipDirection aDir,

                                    CEikColumnListBox *aListBox,

                                    TInt aItemIndex,

                                    TInt aColumnNumber);

    // implementation

    static TBool DoClipToFit(

        TDes& aBuffer,

        const CFont& aFont,

        TInt aMaxWidthInPixels,

        TClipDirection aDir,

        TInt aClipWidth,

        const TDesC& aClipString );

    /**

    * Wraps a string to an array of pointers.

    * The number of lines and line widths are specified by aLineWidthArray.

    * The pointers in aWrappedArray point to positions inside aWrappedString.

    *

    * @param aStringToWrap      String that needs to be wrapped

    * @param aLineWidthArray    Line widths in pixels

    * @param aFont              Used font

    * @param aWrappedArray      Pointers to wrapped lines

    */

    IMPORT_C static void WrapToArrayL( 

        const TDesC& aStringToWrap,

        const CArrayFix<TInt>& aLineWidthArray,

        const CFont& aFont,

        CArrayFix<TPtrC>& aWrappedArray);

    /**

    * Wraps a string to an array of pointers.

    * Constant line width is given.

    * The pointers in aWrappedArray point to positions inside aWrappedString.

    *

    * @param aStringToWrap      String that needs to be wrapped

    * @param aLineWidth         Constant line width in pixels

    * @param aFont              Used font

    * @param aWrappedArray      Pointers to wrapped lines

    */

    IMPORT_C static void WrapToArrayL( 

        const TDesC& aStringToWrap,

        TInt aLineWidth,

        const CFont& aFont,

        CArrayFix<TPtrC>& aWrappedArray );

    /**

    * Wraps a string to an array of pointers and clips at the end

    * of the last line if there aren't enough lines to accomodate

    * the entire text. When clipping three dots are inserted at the

    * end of the last line.

    * The number of lines and line widths are specified by aLineWidthArray.

    * The pointers in aWrappedArray point to positions inside aWrappedString.

    *

    * Expect the string to be modified if clipping is needed.

    * (Clipping character KEllipsis is inserted at the ending point)

    *

    * @param aStringToWrap      String that needs to be wrapped

    * @param aLineWidthArray    Line widths in pixels

    * @param aFont              Used font

    * @param aWrappedArray      Pointers to wrapped lines

    */

    IMPORT_C static void WrapToArrayAndClipL( 

        TDes& aStringToWrap,             

        const CArrayFix<TInt>& aLineWidthArray, 

        const CFont& aFont,                     

        CArrayFix<TPtrC>& aWrappedArray );       

    /**

    * Chops a string 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 number of lines and line widths are specified by aLineWidthArray.

    * The pointers in aChoppedArray point to positions inside aStringToChop.

    *

    * Expect the string to be modified if clipping is needed

    * (Clipping character KEllipsis is inserted in the end of the lines)

    *

    * @param aStringToChop      String that needs to be chopped

    * @param aLineWidthArray    Line widths in pixels

    * @param aFont              Used font

    * @param aChoppedArray      Pointers to chopped lines

    */

    IMPORT_C static void ChopToArrayAndClipL(

        TDes& aStringToChop,             

        const CArrayFix<TInt>& aLineWidthArray, 

        const CFont& aFont,                    

        CArrayFix<TPtrC>& aChoppedArray);

    /**

    * Chops a string 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.

    * Constant line width is given.

    * The pointers in aChoppedArray point to positions inside aStringToChop.

    *

    * Expect the string to be modified if clipping is needed

    * (Clipping character KEllipsis is inserted in the end of the lines)

    *

    * @param aStringToChop      String that needs to be chopped

    * @param aLineWidth         Constant line width in pixels

    * @param aFont              Used font

    * @param aChoppedArray      Pointers to chopped lines

    */

    IMPORT_C static void ChopToArrayAndClipL(

        TDes& aStringToChop,             

        TInt aLineWidth, 

        const CFont& aFont,                    

        CArrayFix<TPtrC>& aChoppedArray );

    /**

    * Wraps a string (aStringToWrap) into lines according to the

    * number of lines and line widths specified in aLineWidthArray. 

    * Inserts '\n' at the end of lines. 

    * Copies the result into aWrappedString.

    * Leaves if aWrappedString isn't big enough.

    *

    * @param aStringToWrap      String that needs to be wrapped

    * @param aLineWidthArray    Lines widths in pixels

    * @param aFont              Used font

    * @param aWrappedString     Wrapped string 

    */

    IMPORT_C static void WrapToStringL( 

        const TDesC& aStringToWrap,

        const CArrayFix<TInt>& aLineWidthArray,

        const CFont& aFont,

        TDes& aWrappedString );

   /**

    * Wraps a string (aStringToWrap) into lines according to the

    * number of lines and line widths specified in aLineWidthArray. 

    * Inserts '\n' at the end of lines. 

    * Clips the last line if there aren't enough lines to

    * fit the entire string. 

    * Copies the result into aWrappedString.

    * Leaves if aWrappedString isn't big enough.

    *

    * @param aStringToWrap      String that needs to be wrapped

    * @param aLineWidthArray    Width of lines in pixels

    * @param aFont              Used font

    * @param aWrappedString     Wrapped string 

    */

    IMPORT_C static void WrapToStringAndClipL(

        const TDesC& aStringToWrap, 

        const CArrayFix<TInt>& aLineWidthArray, 

        const CFont& aFont, 

        TDes& aWrappedString ); 

    /**

     * This routine is used to strip away a set of characters from

     * a descriptor.

     *

     * Useful for example for listboxes to make sure strings from

     * network or typed by the end user does not have tab or linefeed

     * characters. (as those will make listbox broken.)

     * 

     * @param   aDes         Parameter to change

     * @param   aCharacters  A set of characters to remove

     *

     * There exists predefined character sets to remove:

     *    KAknStripTabs

     *    KAknStripListControlChars  (\t's and \n's and \r's)

     */

    IMPORT_C static void StripCharacters(TDes &aDes, const TDesC &aCharacters);

    /**

     * This routine is used to replace all control chars with a single 

     * character, usually a whitespace.

     *

     * @param   aDes         Parameter to change

     * @param   aCharacters  A set of characters to remove

     * @param   aReplacement a character used as replacement

     *

     *    KAknReplaceTabs

     *    KAknReplaceListControlChars  (\t's and \n's)

     */

    IMPORT_C static void ReplaceCharacters(TDes &aDes, const TDesC &aChars, TChar aReplacement);

    /**

     * This routine is used to remove extra whitespaces from text before 

     * showing on screen

     *

     * @param   aDes                   Parameter to change

     * @param   aWhiteSpaceCharacters  A set of whitespace characters to remove

     */

    IMPORT_C static void PackWhiteSpaces(TDes &aDes, const TDesC &aWhiteSpaceChars);

    // non-exported implementation

    static void WrapToStringL(

        const TDesC& aStringToWrap, 

        const CArrayFix<TInt>& aLineWidthArray, 

        const CFont& aFont, 

        TDes& aWrappedString,

        TInt aFlags,

        TInt aDirectionality );

    static void WrapToArrayL( 

        TDes& aStringToWrap,

        const CArrayFix<TInt>* aLineWidthArray, 

        const CFont& aFont,

        CArrayFix<TPtrC>& aWrappedArray,

        TInt aLineWidth,

        TInt aFlags,

        TInt aDirectionality );

    static void ChopToArrayAndClipL(

        TDes& aStringToChop,             

        const CArrayFix<TInt>* aLineWidthArray,

        const CFont& aFont,                 

        CArrayFix<TPtrC>& aChoppedArray,

        TInt aLineWidth );    

    /**

    * This utility is used to see if a text is empty according to the conventions of 

    * Avkon.

    *

    * @param    aTextToTest

    * @return   ETrue if the text is empty according to Avkon

    */

    static TBool IsEmptyText( const TDesC& aTextToTest );

    /**

     * This routine is used to convert between arabic-indic digits and european digits.

     * based on existing language setting. So it'll convert any digit from the string

     * to use either european digits or arabic-indic digits based on current settings.

     *

     * NOTE: THis method can be also called in european release. The method is required

     * to do the correct thing with all the languages.

     *

     * This method should only be used just before displaying the number as unicode string.

     * Also, never store the converted string as unicode.

     *

     * @since 2.0

     * @param   aDes                    Parameter to change

     */

    IMPORT_C static void LanguageSpecificNumberConversion(TDes &aDes);

    /**

     * This routine is used to convert digits from any digit format to another format eg. from 

     * european digits to arabic-indic digits.

     *

     * @since 2.0

     * @param aDes                      Parameter to change. It can contain digits from several digit types.

     * @param aDigitType                Destination digit type.

     */

    IMPORT_C static void ConvertDigitsTo( TDes& aDes, TDigitType aDigitType );

    /**

    * Convenience routine to obtain the directionality of the current input language

    * This routine will attempt to access this information in a system-efficient way.

    *

    * This is not to be confused with either the directionality of the display text 

    * language or (a closely associated concept) the layout direction of the UI 

    * (accessed via AknLayoutUtils::LayoutMirrored() )

    * 

    * @since 2.0

    * @return TBidiText::ELeftToRight if the current input language is left to right

    *         TBidiText::ERightToLeft if the current input langauge is right to left     

    */

    IMPORT_C static TBidiText::TDirectionality CurrentScriptDirectionality();

    /**

    * Method used to constrain the digit type to use to that consisted with the current input language

    * 

    * @since 2.0

    * @returns TDigitType consistent with the current input language

    */

    static TDigitType InputLanguageFilteredDigitType();

    /**

    * Method used to constrain the digit type to use to that consisted with the current display text language

    * 

    * @since 2.0

    * @returns TDigitType consistent with the current input language

    */

    static TDigitType DisplayTextLanguageFilteredDigitType();

    /**

    * Returns the digit type to be used for editors that are purely numeric in quality.

    *

    * @since 2.0

    * @returns TDigitType to use for purely numeric editors

    */ 

    IMPORT_C static TDigitType NumericEditorDigitType();

    /**

     * This routine is used to convert between arabic-indic digits and european digits.

     * based on existing language setting. So it'll convert any digit from the string

     * to use either european digits or arabic-indic digits based on current settings.

     *

     * This routine builds in the constraints imposed by current display text languages. 

     *

     * The number of characters in the buffer is not changed by this routine. It can therefore be 

     * safely used easily with existing (modifiable) descriptors.

     *

     * This method should only be used just before displaying the number as unicode descriptor.

     * Never store the converted string.

     *

     * @since 2.0

     * @param   aDes                    Parameter to change

     */

    IMPORT_C static void DisplayTextLanguageSpecificNumberConversion(TDes &aDes);

    /**

    * Returns the digit type to be used for editors that are alphanumeric.

    * (Note that these editors may be configurable to be purely numeric - that is have a numeric

    * mode, but they remain alphanumeric editors for the sake of this API.)

    *

    * This may be useful for instance for input processors that convert numeric key events to the 

    * currently set input digit type.

    *

    * @since 2.0

    * @returns TDigitType to editors with alphanumeric capability

    */ 

    IMPORT_C static TDigitType TextEditorDigitType();

    enum TDigitModeQueryType {

        EDigitModeEditorDefault, // in editors by default whether western or foreign digits are used (gen.editors, both text and numbers)

        EDigitModeUserModifiableEditor, // in editors whether user can modify digitmode with keypad

        EDigitModeShownToUser, // in all components when displaying digits

        EDigitModeNumberEditor, // number, time, date, notification texts (1st group of editors)

        EDigitModeLatinNumberEditor // e-mail, password, PIN codes, etc. (3rd group, where only latin can be used)

    };

    /**

     * This routine can be used to check what modes digits can be on.

     *

     * It uses input language, display language and the setting from general settings

     * to calculate whether foreign digits need to be used.

     *

     * This is useful for editor implementation and anyone that needs to convert

     * digits for display.

     * 

     * @since 2.0

     * @param aQueryType   what is the situation where the digits are to be used.

     * @returns ETrue to indicate whether digit conversions need to be used.

     * @returns EFalse to indicate that no conversion is needed.

     */

    IMPORT_C static TBool DigitModeQuery(TDigitModeQueryType aQueryType = EDigitModeShownToUser);

    /** 

     * Converts a filename ABCDE.EXT to format which is suitable for display.

     * This method is needed for bi-directional language support.

     * The method adds directionality markers to the filename so that the

     * filename can correctly be rendered to screen.

     *

     *

     * @since 2.6

     * @param aDes contains the file name in logical format. 

     * @returns file name in logical format with needed directionality markers.

     */

    IMPORT_C static HBufC* ConvertFileNameL(const TDesC& aDes);

    /**

    * @deprecated

    * Do not use. This method will be removed.

    */

    IMPORT_C static HBufC* LoadScalableTextL(CCoeEnv& aCoe, TInt aResourceId);

    /**

    * @deprecated

    * Do not use. This method will be removed.

    */

    IMPORT_C static HBufC* LoadScalableTextLC(CCoeEnv& aCoe, TInt aResourceId);

    /**

    * @deprecated

    * Do not use. This method will be removed.

    */

    IMPORT_C static TInt LoadScalableText(CCoeEnv& aCoe, TInt aResourceId, TDes& aBuffer ); 

    /**

    * @deprecated

    * Do not use. This method will be removed.