/*
* Copyright (c) 2002-2010 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;
class MAknsSkinInstance;

/**
 * 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.
    */
    IMPORT_C static HBufC* ClipAccordingScreenOrientationLC(CCoeEnv& aCoe, HBufC* aBuf); 

    /**
    * Utility method used in scalable UI for choosing the longest fitting text variant.
    * Truncating and wrapping methods in classes AknTextUtils and AknBidiTextUtils do
    * the choice by themselves, so whenever they are used to process the text, it is not
    * necessary to call this method.
    *
    * Applications do not need to call this method if they pass their localized texts
    * to Avkon's UI components.
    *
    * @since 2.8
    * 
    * @param aText Text containing one or many variants with varying text widths,
    * separated with the character 0x0001. The text is supposed to be 
    * in logical order.
    * @param aFont Font used to render the text.
    * @param aMaxWidthInPixels Max width in pixels.
    *
    * @ret Longest fitting text. If none of the variants fits,
    * the shortest one in pixels is returned.
    */
    IMPORT_C static TPtrC ChooseScalableText(
        const TDesC& aText,
        const CFont& aFont,
        TInt aMaxWidthInPixels );
    };

_LIT(KAknStripTabs, "\t");
_LIT(KAknStripListControlChars, "\t\n");
_LIT(KAknReplaceTabs, "\t");
_LIT(KAknReplaceListControlChars, "\t\n");
_LIT(KAknCommonWhiteSpaceCharacters, " \n\t\r");

/**
 * These are part of Selection service and they should be called by application's HandleCommandL() to get
 * menus and cba's handled automatically for selection service.
 *
 * The right way to implement these would be to have dialogs with names "Selection List", "MultiSelection List"
 * and "Markable list" and make them keep a listbox inside it. (look at CAknPopupList, it does similar things)
 *
 * See CAknSelectionListDialog and CAknMarkableListDialog from aknselectionlist.h, they provide better
 * interface for applications.
 */
class AknSelectionService
    {
public:
    /** Helper function to implement ProcessCommandL() for selection list dialogs
     */
    IMPORT_C static void HandleSelectionListProcessCommandL(
        TInt aCommand,
        CEikListBox* aListBox);

    /** Helper function to implement ProcessCommandL() for selection list dialogs
     */
    IMPORT_C static void HandleMultiselectionListProcessCommandL(
        TInt aCommand,
        CEikListBox* aListBox);

    /** Helper function to implement ProcessCommandL() for markable list dialogs
     */
    IMPORT_C static void HandleMarkableListProcessCommandL(
        TInt aCommand,
        CEikListBox* aListBox);

    /** Helper function to implement ProcessCommandL() for menu lists
     */
    IMPORT_C static TKeyResponse HandleMenuListOfferKeyEventL(
        const TKeyEvent& aKeyEvent,
        TEventCode aType,
        CEikListBox* aListBox);

    /** Helper function to implement DynInitMenuPaneL() for markable list dialogs
     */
    IMPORT_C static void HandleMarkableListDynInitMenuPane(
        TInt aResourceId,
        CEikMenuPane *aMenu,
        CEikListBox *aListBox);

    /** Helper function to implement DynInitMenuPaneL() for markable list dialogs
     */
    IMPORT_C static void HandleMarkableListDynInitMenuItem(
        CEikMenuPane *aMenu,
        CEikListBox *aListBox,
        TInt aCommandId,
        TBool aCanBeAppliedToMultipleItems);

    /** Helper function to implement command handling for markable list dialogs
     */
    IMPORT_C static void HandleMarkableListUpdateAfterCommandExecution(
        CEikListBox *aListBox);

    /** Helper function to position list highlight correctly after item removal
     */
    IMPORT_C static void HandleItemRemovalAndPositionHighlightL(
        CEikListBox *aListBox,
        TInt aValueOfCurrentItemIndexBeforeRemoval,
        TBool aCurrentItemWasRemoved);

    // This one updates selectionindexes too.
    /** Helper function to position list highlight correctly after item removal
     *
     * It also updates selection index array based on information about which
     * items were removed.
     */
    IMPORT_C static void HandleItemRemovalAndPositionHighlightL(
        CEikListBox *aListBox,
        TInt aValueOfCurrentItemIndexBeforeRemoval,
        CArrayFix<TInt> &aIndexesOfRemovedItemsBeforeRemoval);
    };



class CAknSearchField;

/** 
 * This class implements find requirements from component specifications. This
 * class works also as documentation of how to use different find components.
 * (The implementation has been copied from the example application which 
 * implements find and replaced the code with calls to these static functions).
 *
 * There is no reason for an application to use this class directly. 
 * Application should use CAknSelectionListDialog instead. This class is public
 * only because sometimes it is necessary to access the low level behaviour of
 * find to implement similar functionality in places independent of find; or if
 * @c CAknSelectionListDialog is not used for some reason.
 */
class AknFind
    {
public:

    /*
     * Implements the event handlers for the find pane. This method must be
     * called when a @c ProcessCommandL event is received and a find pane is on
     * the screen.
     *
     * @param aCommand Command id.
     * @param aListBox Pointer to listbox control.
     * @param aSearchField Pointer to search field control.
     * @param aParentControl Parent control.
     */
    IMPORT_C static void HandleFindPopupProcessCommandL(
                        TInt aCommand, 
                        CEikListBox* aListBox, 
                        CAknSearchField* aSearchField, 
                        CCoeControl* aParentControl);
    
    /*
     * Handles key events for the find pane. This method must be called when
     * control receives @c OfferKeyEventL event.
     *
     * @param aKeyEvent The key event.
     * @param aType The type of key event:@c TEventCode.
     * @param aListBoxParent Pointer to the parent control.
     * @param aListBox Pointer to listbox control.
     * @param aSearchField Pointer to search field control.
     * @param isFindPopup @c ETrue if popup find pane, @c EFalse if normal find
     *        pane.
     * @param aNeedRefresh @c ETrue when find pane is redrawn.
     */    
    IMPORT_C static TKeyResponse HandleFindOfferKeyEventL(
                        const TKeyEvent& aKeyEvent, 
                        TEventCode aType, 
                        CCoeControl* aListBoxParent, 
                        CEikListBox* aListBox, 
                        CAknSearchField* aSearchField, 
                        TBool isFindPopup, 
                        TBool &aNeedRefresh);

    /*
     * Do not use this method.
     *
     * @deprecated Use @c AknFind::HandleFixedFindSizeChanged() and 
     *             @c AknFind::HandlePopupFindSizeChanged instead.
     *        
     */
    IMPORT_C static void HandleFindSizeChanged(
            CCoeControl* aParentControl, 
            CEikListBox* aListBox, 
            CAknSearchField* aSearchField, 
            TBool ispopup = ETrue, 
            TInt aFindWindowResourceId = R_AVKON_POPUP_FIND_WINDOW, 
            TInt aListAreaId = R_AVKON_LIST_GEN_PANE, 
            TInt aListResourceIdWithFindPopup = 
                                R_AVKON_LIST_GEN_PANE_WITH_FIND_POPUP, 
            TInt aFindWindowParentResourceId = 
                                R_AVKON_MAIN_PANE_WITH_STATUS_PANE);

    /** 
     * This is the new typesafe (and easier to use) version of @c
     * HandleFindSizeChanged(). Use this instead of (deprecated) @c
     * HandleFindSizeChanged().
     *
     * @param aParentControl Parent control.
     * @param aListBox Column list, optional and available only with column 
     *                 lists.
     * @param aSearchField Pointer to search field control.
     */
    IMPORT_C static void HandleFixedFindSizeChanged(
            CCoeControl* aParentControl,
            CAknColumnListBox* aListBox, // only available with column lists
            CAknSearchField* aSearchField);
    
    /** 
     * This is the new typesafe(and easier to use) version of @c 
     * HandleFindSizeChanged(). Use this instead of (deprecated) @c
     * HandleFindSizeChanged().
     *
     * @param aParentControl Parent control.
     * @param aListBox Pointer to listbox control.
     * @param aSearchField Pointer to search field control.
     */
    IMPORT_C static void HandlePopupFindSizeChanged(
                            CCoeControl* aParentControl,
                            CEikListBox* aListBox,  //available with all lists.
                            CAknSearchField* aSearchField);
    
    /**
     * Creates layout for a find pane and for a list. This method must be called
     * in @c SizeChanged() method of an container.
     *
     * @since 2.6
     *
     * @param aParentControl Parent control.
     * @param aListBox Pointer to listbox control.
     * @param aSearchField Pointer to search field control.
     * @param aFindWindow LAF specific table line for find window.
     * @param aListArea LAF specific table for list box area.
     * @param aIsPopup @c ETrue if popup find pane, @c EFalse if normal find
     *        pane.
     * @param aFindWindowParent LAF specific table line for find parent.
     */
    IMPORT_C static void HandleFindSizeChangedLayouts(
                            CCoeControl* aParentControl, 
                            CEikListBox* aListBox, 
                            CAknSearchField* aSearchField, 
                            const TAknWindowLineLayout& aFindWindow,
                            const TAknWindowLineLayout& aListArea,
                            TBool aIsPopup,
                            const TAknWindowLineLayout& aFindWindowParent );

public:

    /**
     * Checks if @c aItemText matches @c aSearchText. 
     *
     * @param aItemText List box item text.
     * @param aSearchText Searched text.
     * 
     * @return @c ETrue if list box item text @c aItemText matches @c 
     *         aSearchText otherwise @c EFalse.
     */
    IMPORT_C static TBool IsFindMatch(const TDesC& aItemText, 
                                      const TDesC& aSearchText);

    /**
     * Tests if aCh is a word separator character as described in S60.
     *
     * @param aCh Comperative character.
     *
     * @return @c ETrue if aCh is a word separator character as described in
     * S60 otherwise @c EFalse.
     */
    IMPORT_C static TBool IsFindWordSeparator(TChar aCh);

    
    /**
     * Checks if @c aItemText matches @c aSearchText. 
     * Calls UpdateNextCharsL() if findutil is not supported.
     *
     * @since 5.0
     * @param aItemText List box item text.
     * @param aSearchText Searched text.
     * @param aNextChars Reference to the next characters for the adaptive search grid
     *        The HBufC buffer may be re-allocated by this method. 
     *        In that case the pointer reference is modified to point to the re-allocated object.     
     * 
     * @return @c ETrue if list box item text @c aItemText matches @c 
     *         aSearchText otherwise @c EFalse.
     */
    IMPORT_C static TBool IsAdaptiveFindMatch( const TDesC& aItemText, 
			    		       const TDesC& aSearchText,			
			       		       HBufC*& aNextChars );

    /**
     * Update next characters if find pane state was changed.
     *
     * @since 5.0
     * @param aNextChars Next characters for the adaptive search grid
     * @param aCh Criteria from the search field.    
     */
    static void UpdateNextCharsL( HBufC*& aNextChars, TChar aCh );
    
    /**
     * For Devanagari adaptive search     
     * Update next characters if find pane state was changed.
     *
     * @since 5.0
     * @param aNextChars reference to the next characters for the adaptive search grid
     * @param aItemString string we are searching.    
     */
    static void UpdateNextCharsL( HBufC*& aNextChars, const TDesC& aItemString );
    
    /**
     * Update next chars from the list box item text, when search field if empty.
     * This need to be done for update next characters for adaptive grid
     * works faster then calling IsAdaptiveFindMatch(). 
     *
     * @since 5.0
     * @param aNextChars Reference to the next characters for the adaptive search grid
     *        The HBufC buffer may be re-allocated by this method. 
     *        In that case the pointer reference is modified to point to the re-allocated object.     
     * @param aItemString List box item text.
     */
    IMPORT_C static void UpdateNextCharsFromString( HBufC*& aNextChars, const TDesC& aItemString );

    /**
     * Update next chars from the list box item text according to the bitflag.
     * Use to exclude columns from the listbox string. For example icon index columns. 
     *
     * @since 5.0
     * @param aInputText List box item text
     * @param aColumnFlag The bit flag shows which columns take into account
     * @param aOutText Updated list box item text accoding to bit flag
     */
    IMPORT_C static void UpdateItemTextAccordingToFlag( const TDesC& aInputText, 
		  		 			TBitFlags32 aColumnFlag, 
							TDes& aOutText );

    /**
     * Helper function to handle find pane's visibility.
     *
     * @param aSearchField Pointer to search field control.
     * @param ispopup @c ETrue if popup find pane, @c EFalse if normal find 
     *        pane.
     * @param textchanged @c ETrue when text in @c CAknSearchField has changed.
     * @param aNeedRefresh @c ETrue when find pane is redrawn.
     */
    static void HandleFindPaneVisibility(CAknSearchField* aSearchField, 
                                         TBool ispopup, 
                                         TBool textchanged, 
                                         TBool &aNeedRefresh);
    };


/** 
 * Utility class to initialize editor control. Use this in conjunction with @c
 * AknLayoutUtils::LayoutEdwin(). The class is not fully implemented yet.
 */
class AknEditUtils
    {
    public:
    
    /** Basic elements that are needed for the basic editing functions. */
    struct SAknEditorParameters 
    {
        /** The maximum available space that can be used for one text. */
        TInt iEditingSpace;
        
        /** Size of the editing window. */
        TInt iEditingWindow;
        
        /**
         * Character case effects on the style of entering characters.
         * Available alternatives are Upper case, Lower case and Text case.
         */ 
        TInt iCharacterCase;
        
        /** 
         * Specifies from which edge the current line is filled with the
         * inserted characters.
         */
        TInt iJustification;
        
        /** Is user allowed to move the insertion point. */ 
        TBool iAllowedToMoveInsertionPoint;
        
        /** Is cursor blinking or not. */
        TBool iCursorYesNo;
        
        /** Is overflow active or not.  */  
        TBool iOverflowYesNo;
    };

    IMPORT_C static void ConstructEditingL(CEikEdwin* aEdwin, TInt aResourceId);
    IMPORT_C static void ConstructEditingL(CEikEdwin* aEdwin, TResourceReader& aReader);
    IMPORT_C static void ConstructEditingL(CEikEdwin* aEdwin, const SAknEditorParameters &aParams);

/**
 *  Configures edwin editor. Use AknLayoutUtils::LayoutEdwin() with this method.
 *
 *  @param aEdwin Edwins created with new.
 *  @param aEditingSpace maximum number of characters for the editor
 *  @param aEditingWindow maximum number of lines in the editor
 *  @param aCharacterCase initial character case:
 *          EAknEditorCharactersUpperCase = EAknEditorUpperCase,
 *          EAknEditorCharactersLowerCase = EAknEditorLowerCase,
 *          EAknEditorCharactersTextCase = EAknEditorTextCase,
 *          EAknEditorCharactersTitleCase = EAknEditorTitleCase
 *
 *  @param aJustification alignment for the editor text ( EAknEditorAlignCenter, 
 *         EAknEditorAlignLeft, EAknEditorAlignRight)
 *  @param aAllowedToMoveInsertionPoint user can move cursor
 *  @param aCursorYesNo is cursor visible or not.
 *  @param aOverflowYesNo
 */
    IMPORT_C static void ConstructEditingL(CEikEdwin* aEdwin, 
                       TInt aEditingSpace, 
                       TInt aEditingWindow, 
                       TInt aCharacterCase, 
                       TInt aJustification, 
                       TBool aAllowedToMoveInsertionPoint, 
                       TBool aCursorYesNo, 
                       TBool aOverflowYesNo);
                       
/**
 *  Configures edwin editor. Use AknLayoutUtils::LayoutEdwin() with this method.
 *  
 *  @param aEdwin Edwins created with new.
 *  @param aEditingSpace maximum number of characters for the editor
 *  @param aEditingWindow maximum number of lines in the editor
 *  @param aCharacterCase initial character case:
 *          EAknEditorCharactersUpperCase = EAknEditorUpperCase,
 *          EAknEditorCharactersLowerCase = EAknEditorLowerCase,
 *          EAknEditorCharactersTextCase = EAknEditorTextCase,
 *          EAknEditorCharactersTitleCase = EAknEditorTitleCase
 *
 *  @param aJustification alignment for the editor text ( EAknEditorAlignCenter, 
 *         EAknEditorAlignLeft, EAknEditorAlignRight)
 *  @param aAllowedToMoveInsertionPoint user can move cursor
 *  @param aCursorYesNo is cursor visible or not.
 *  @param aOverflowYesNo
 *  @param aIsResizeable is edwin resizeable (one line editor should use EFalse, in order to have proper scrolling)
 */
    IMPORT_C static void ConstructEditingL(CEikEdwin* aEdwin, 
                                              TInt aEditingSpace, 
                                              TInt aEditingWindow, 
                                              TInt aCharacterCase, 
                                              TInt aJustification, 
                                              TBool aAllowedToMoveInsertionPoint, 
                                              TBool aCursorYesNo, 
                                              TBool aOverflowYesNo,
                                              TBool aIsResizable);

    };

/** Automatic numbering for list items. (DEPRECATED)
 * Just create this kind of object and attach it to a listbox, and you'll
 * have automatic numbering. 
 *
 *
 * You'll need to call UpdateL() each time you modify the listbox's model!
 */
class CListBoxNumbers : public CBase
    {
public:
    IMPORT_C CListBoxNumbers(CEikTextListBox* aListBox);
    IMPORT_C void ConstructL();
    IMPORT_C void UpdateL();
private:
    CEikTextListBox* iListBox;
    };

class CAknListBoxFilterItems;

    /** 
    * This class shows how application should build its model for filtered
    * items. Application should not use this directly, if it has it's own model
    * or if there's any special things needed for @c MatchableTextArray.
    * Application can derive from this though. All listboxes use 
    * @c CAknFilteredTextListBoxModel by default. @c CreateFilter() call 
    * enables it.
    * @since S60 0.9
    */
class CAknFilteredTextListBoxModel : public CTextListBoxModel, public MDesCArray
    {
public: // public interface for apps
    /**
    * Creates a @c CAknListBoxFilterItems and thus enables filtering of list
    * items.
    * @param aListBox List box from which one or more items can be selected.
    * @param aSearchField Search field control.
    */
    IMPORT_C void CreateFilterL(CEikListBox* aListBox, CAknSearchField* aSearchField);
    /**
     * removes previously added filter from model
     */
    IMPORT_C void RemoveFilter();
    /**
    * Access function for the filter.
    * @return Pointer to the listbox filter.
    */
    IMPORT_C CAknListBoxFilterItems* Filter() const;
    /**
    * Destructor.
    */
    IMPORT_C ~CAknFilteredTextListBoxModel();
public: // from CTextListBoxMode
    /**
    * Implementation of @c CTextListBoxModel::NumberOfItems()
    * @return The number of items the list box has.
    */
    IMPORT_C virtual TInt NumberOfItems() const;
    /**
    * Returns the text of the specified item.
    * @param aItemIndex Index to the item.
    * @return The text of item in given index.
    */
    IMPORT_C virtual TPtrC ItemText(TInt aItemIndex) const;
public: // from MEikTextListBoxModel (default filtering string conversions)
    /**
    * Implementation of @c CTextListBoxModel::MatchableTextArray()
    * @return Pointer to the text array.
    */
    IMPORT_C const MDesCArray* MatchableTextArray() const;

private:
    CAknListBoxFilterItems* iFilter; // owned
private: // From MdesCArray (these implement default matchabletextarray for filtering.)
    IMPORT_C TInt MdcaCount() const;
    IMPORT_C TPtrC MdcaPoint(TInt aIndex) const;
private: // from MListBoxModel
    IMPORT_C virtual TAny* MListBoxModel_Reserved();
    };

    /** 
    * Listbox item filtering. This class is designed to be stored inside
    * a listbox model and the model should call this in its @c NumberOfItems()
    * and @c ItemText() implementation. The model must be given to this class
    * and it must have @c MatchableTextArray() implemented correctly.
    * @c HandleOfferKeyEvent() should be called from the same offer key event
    * implementation which forwards the keys to listbox and search field
    * 
    * If you have both markable list and find at the same time, you should call
    * @c ResetFiltering() before executing the command for marked items. This
    * ensures that the ListBox's @c SelectionIndexes() returns all items instead
    * of only those items that are visible. Selected *items can be found under
    * @c CAknListBoxFilterItems::SelectionIndexes().
    *
    * @since S60 0.9
    * 
    */
class CAknListBoxFilterItems : public CBase, public MCoeControlObserver
    {
public:
    /**
    * Base class default constructor.
    * @param aListBox Listbox to be filtered,
    * @param aSearchField Listbox search field.
    * @param aModel Listbox model,
    * @param aView A list box view that displays the list items which are
    * currently visible in a list box.
    */
    IMPORT_C CAknListBoxFilterItems(
        CEikListBox *aListBox,
        CAknSearchField *aSearchField,
        MListBoxModel *aModel,
        CListBoxView *aView);

    /**
    * This is for setting empty list text.
    */
    IMPORT_C void ConstructL(); // for setting empty list text.
    /** 
    * This function is to be called when filter is cleared.
    */
    IMPORT_C void ResetFilteringL();
    /** 
    * This function will update filter items state from the search field and
    * listbox. Also updates selection indexes.
    */
    IMPORT_C void UpdateCachedDataL(); // updates iOldSearchCriteria and selection indexes.
    /**
    * Destructor. Frees all resources owned by the object prior to its
    * destruction.
    */
    IMPORT_C ~CAknListBoxFilterItems();    

public: 
    /** 
    * This one gives all indices, not just the ones that are visible.
    * @return Pointer to the array that has all indices.
    */
    IMPORT_C CArrayFix<TInt> *SelectionIndexes();
    /** 
    * This will synchronise the selection indices from the listbox.
    * If you use @c SelectionIndexes(), call this before it.
    * This is heavy operation and goes through all list items.
    */
    IMPORT_C void UpdateSelectionIndexesL();
    /** 
    * This will synchronise the selected index from the listbox.
    * If you use @c SelectionIndexes(), call this before it.
    * This is heavy operation and goes through all list items. 
    * @param aVisibleIndex Index to be updated.
    */
    IMPORT_C void UpdateSelectionIndexL(TInt aVisibleIndex);

public: // Applications should call this in their listbox model implementation
    /** 
    * This is used to ask how many list items are available after filter has
    * been used. Counts visible list items.
    * @return Number of items visible.
    */
    IMPORT_C TInt FilteredNumberOfItems() const;
    /** 
    * This is used to fetch the content of a list item after filter has been
    * used.
    * @param aVisibleItemIndex The index of visible item.
    * @return Index to the original item array.
    */
    IMPORT_C TInt FilteredItemIndex(TInt aVisibleItemIndex) const;

public: // Needed to change the correct item.

    /** 
    * Returns number of original list items.
    * @return Number of all items.
    */
    IMPORT_C TInt NonFilteredNumberOfItems() const; // this always returns >= FilteredNumberOfItems()
    /** 
    * Finds the list item on the screen when the item array index is given.
    * @param aOriginalIndex Item index.
    * @return Matching index from original array. Returns -1 if the Index is
    * not visible.
    */
    IMPORT_C TInt VisibleItemIndex(TInt aOriginalIndex) const;
public: 
    /** 
    * For building @c MdcaPoint() of the model's @c MatchableTextArray.
    * This method builds the default value for @c MatchableTextArray.
    * @param aText Pointer descriptor.
    * @return Modified text.
    */
    IMPORT_C TPtrC DefaultMatchableItemFromItem(TPtrC aText);

public: 
    /** 
    * Applications should call this in @c OfferKeyEventL() which gives keys to
    * listbox and search field.
    */
    IMPORT_C void HandleOfferkeyEventL();

   
    /** 
    * When you change the list item array you should call this method.
    */
    IMPORT_C void HandleItemArrayChangeL();

public: // MCoeControlObserver
    /**
    * Sets the observer.
    * @param aObserver Pointer to the observer.
    */
    IMPORT_C void SetObserver(MCoeControlObserver *aObserver);
    /**
    * Editor sends messages to this object as control events.
    * @param aControl The control that sent the event.
    * @param aEventType The event type.
    */
    IMPORT_C void HandleControlEventL(CCoeControl *aControl, TCoeEvent aEventType);

public: // For FEP
    /**
    * Sends key events to FEP. This is used to resend key event to FEP if
    * @c AknFind's @c HandleOfferKeyEventL() gets the key while search field
    * has no focus. If search field has a focus, the key events go directly to
    * the editor and this is not called.
    * @param aValue The character code for an @c EEventKey.
    */
    IMPORT_C void DeferredSendKeyEventToFepL(TUint aValue);
    /**
    * This gets called from @c DeferredSendKeyEventToFepL().
    * This does the actual sending of a key event. Does not support more than
    * one event at the time.
    * @param aFilterItems Pointer to the @c CAknListBoxFilterItems object.
    * @return Always returns 0.
    */
    static TInt IdleCallBack(TAny *aFilterItems);

public: // For size changed
    /**
    * @c AknFind uses this to inform us who is the parent control owning the
    * listbox and search field. This control should be window-owning control and
    * it will be used to resize the listbox when changes to the filtering
    * happens.
    * @param aControl Pointer to the control.
    */
    IMPORT_C void SetParentControl(CCoeControl *aControl);
   /**
    * @c AknFind uses this to inform us that we have popup find. Applications 
    * shouldn't call this.
    */
    IMPORT_C void SetPopup();

public: // For detaching and attaching list, findbox, model and view...
    /**
    * Attaches or detaches list used by the filtering.
    * @since S60 2.0
    * @param aListBox Pointer to listbox or @c NULL.
    */
    IMPORT_C void SetListBox(CEikListBox *aListBox);
    /**
    * Attaches or detaches find pane used by the filtering.
    * @since S60 2.0
    * @param aSearchField Pointer to findbox or @c NULL.
    */
    IMPORT_C void SetSearchField(CAknSearchField *aSearchField);
    /**
    * Attaches or detaches list model used by the filtering.
    * @since S60 2.0
    * @param aModel a pointer to list model or @c NULL.
    */
    IMPORT_C void SetModel(MListBoxModel *aModel);
    /**
    * Attaches or detaches list view used by the filtering.
    * @since S60 2.0
    * @param aView a pointer to list view or @c NULL.
    */
    IMPORT_C void SetView(CListBoxView *aView);
    
public:
    /**
    * This function just returns pointer to the search field.
    * @return Pointer to the search field.
    */
    IMPORT_C CCoeControl *FindBox() const;

    /**
     * An improved version of DeferredSendKeyEventToFepL. It sends a 
     * @c TKeyEvent rather than just key code. Thus the correct key 
     * event can be send to FEP on QWERTY keyboard.
     * @since S60 5.0
     * @param aEvent Event send to FEP.
     */
    void DeferredSendFullKeyEventToFepL(const TKeyEvent& aEvent);

private:
    void NoCriteriaL(TBool aUpdateAS = ETrue); // remove criteria completely.
    void TightenCriteriaL(const TDesC& aCriteria); // slow operation (do when adding new characters to search criteria)
    void ReleaseCriteriaL(const TDesC& aCriteria); // very slow operation (do when removing characters from search criteria)
    // EmptyListText handling
    void InstallEmptyTextL();
    void UninstallEmptyTextL();
    // Selections -- these methods form a pair, 
    // you must call Fetch first and then push.
    void FetchSelectionIndexesFromListBoxL();
    void PushSelectionIndexesToListBoxL();
    void ClearNextChars();
    TBool IsAdaptiveSearch() const; 	

    // HandleItemAddition without ResetFilteringL() call
    void HandleItemAdditionL();
    void HandleItemRemovalL();
private:
    TBool IsItemVisible(const TDesC& aMatchableItemString, const TDesC& aSearchText);
    static TBool IsSeparatorCharacter(TChar c);
    TBool IsItemSelected(TInt aRealIndex) const;
private:
    CArrayFix<TInt> *iShownIndexes; // own // uses non-filtered indexes
    CArrayFix<TInt> *iSelectionIndexes; // own   // this uses non-filtered indexes
    HBufC *iOldSearchCriteria; // own
    MListBoxModel *iModel;
    CListBoxView *iView;
    TInt iOldItemCount;
    HBufC* iEmptyListText; // own
    CEikListBox* iListBox;
    CAknSearchField* iSearchField;
    TBuf<256> iMatchableText;
    MCoeControlObserver *iObserver;
    CFindExtension *iExtension;
    TUint iKeyValue;
    CCoeControl *iParentControl;
    TBool iIsPopup;
    TBool iDisableChangesToShownIndexes;  
    };


/** Removing optimization that breaks listbox views 
 * A view which removes optimization from CListBoxView which breaks with lists where all items are not
 * the same layout.
 * Use it like this: 
 *   CListBoxView* MakeViewClassInstanceL() { return new(ELeave) NoOptimizationView<CListBoxView>; }
 */
template<class T>
class NoOptimizationView : public T
    {
public:
    virtual void VScrollTo(TInt aNewTopItemIndex, TRect& aMinRedrawRect)
    {
    // AVKON LAF
    if (this->RedrawDisabled())
        return;
    if (this->iTopItemIndex == aNewTopItemIndex)
        return;
    aMinRedrawRect.SetRect(this->iViewRect.iTl,this->iViewRect.Size());
    this->SetTopItemIndex(aNewTopItemIndex);
    this->Draw(&aMinRedrawRect);
    // end of AVKON LAF
    }
    };


/** This is private class, do not use it except for drawing controls!
 * 
 * Do not use it in applications.
 */


class AknLAFUtils 
    {
public:
    static void DrawLines(CGraphicsContext* aGc, 
                  const TRect& mainpane,
                  TInt x);
    IMPORT_C static void ReplaceColumn(TPtr aTarget, TDesC* aSource,
                                       TDesC* aReplacement, TChar aColumnSeparator,
                                       TInt aColumn);
    };


/**
 * Resource reader class
 *
 * This is utility class for reading listbox resouces.
 *
 * This should be derived from and it reads resource file for you.
 *
 * This seems to be only used by listbox resource readers. (Do not use it in applications)
 */
struct SAknLayoutGfx;
struct SAknLayoutText;
struct SAknLayoutCmd;
struct SAknLayoutGfx;
// Not for apps
struct SAknLayoutPos 
    {
    TInt l, t, r, b, W, H;

    typedef SAknLayoutPos ItemType;
    static void ReadResource(TResourceReader& aReader, ItemType& aTarget);    
    };
template<class T> class CArrayReader;
class CAknGenericReader : public CBase
    {
public:
    IMPORT_C void ConstructL(TInt aResourceId);
    IMPORT_C virtual void ConstructFromResourceL(TResourceReader& aReader);
    IMPORT_C ~CAknGenericReader();

    IMPORT_C const SAknLayoutGfx* GfxItem(TInt aIndex) const;
    IMPORT_C const SAknLayoutText* TextItem(TInt aIndex) const;
    IMPORT_C const SAknLayoutCmd* CmdItem(TInt aIndex) const;
    IMPORT_C const SAknLayoutGfx* AreaItem(TInt aIndex) const;

    CArrayReader<SAknLayoutGfx>* iGfx;
    CArrayReader<SAknLayoutText>* iText;
    CArrayReader<SAknLayoutCmd>* iCmd;
    CArrayReader<SAknLayoutGfx>* iArea;
    };





// Use this to mark that the position in LAF specification is empty.
const TInt AknLayoutUtilsNoValue = ELayoutEmpty;

/** Utility classes to build layout based on European LAF from resource files. (can be used by applications)
 *
 * Methods in this class are designed to be called from your control's SizeChanged() method!
 *
 * This class knows the specification's coordinate data format and ensures that different types of
 * controls are positioned and setup correctly according to European LAF. 
 * 
 * This class helps you with positioning labels, controls, rects and other things to according to LAF specification.
 * (It is NOT trivial to get it correct and this adjusts easily to changes in the LAF specification - if you're not
 * using this, remember to read the whole LAF specification - especially the beginning and the end with color and
 * especially how text margins and widths interact!!)
 *
 * (idea of this class is that when specification of one component changes, only resource file needs to be changed and when you 
 * get new product with new specification format, only this module needs to be changed and resources rewritten from the specification. 
 * And when component's specification changes, only the component need to be changed (usually only change is what components are
 * inside it and how it calls this module.).. => all controls have common format that decides its layout!
 *
 * Parent rectangles are always coordinates of LAF specification's parent rectangle in the screen.
 * 
 * To use this, call one of the methods in your SizeChanged() and then you'll need to make sure you
 * draw the area between controls using ClearBetweenRects() call from egul library. (CCoeControl::Rect() helps with that...)
 *
 * A Tip: You do not want to use any dynamic calculation of layouts! It is almost always an error to do so!
 *        => Do not allow layouts that have not been specified!
 *
 * (If LAF spec has many numbers and you need to dynamically choose between them, then keep the numbers in
 * code as function-local using SAknLayoutText/SAknLayoutRect/... -structs..)
 *
 * You'll want to use TAknLayoutRect and TAknLayoutText too to build layout
 * for your custom controls.
 */
class AknLayoutUtils
    {
public:

    struct SAknLayoutText
    {
    TInt iFont, iC, iL, iR, iB, iW, iJ;
    };
    struct SAknLayoutTextMultiline
    {
    TInt iFont, iC, iL, iR, iB, iW, iJ, iNumberOfLinesShown, iNextLineB;
    };
    typedef SAknLayoutTextMultiline SAknLayoutLabel;
    typedef SAknLayoutTextMultiline SAknLayoutEdwin;
    typedef SAknLayoutText SAknLayoutMfne;
    typedef SAknLayoutText SAknLayoutSecEd;
    struct SAknLayoutRect
    {
    TInt iC, iL, iT, iR, iB, iW, iH;
    };
    typedef SAknLayoutRect SAknLayoutControl;
    typedef SAknLayoutRect SAknLayoutImage;

    /**
    * Deprecated! Do not use!
    */
    IMPORT_C static void LayoutLabel(CEikLabel* aLabel,
                                     const TRect& aLabelParent,
                                     TInt aResourceId,
                                     const CFont* aCustomFont=0);

    /**
    * Deprecated! Do not use!
    */
    IMPORT_C static void LayoutLabel(CEikLabel* aLabel,
                                     const TRect& aLabelParent,
                                     TResourceReader& aReader,
                                     const CFont* aCustomFont=0);

    /** Layouts a label via a structure of layout parameters
    @param aLayout   the structure
     */
    IMPORT_C static void LayoutLabel(CEikLabel* aLabel,
                                     const TRect& aLabelParent,
                                     const SAknLayoutLabel& aLayout,
                                     const CFont *aCustomFont=0);

    /** Layouts a label via a layout compiler output
    @param aLayout   a define from aknlayout.lag file
     */
    IMPORT_C static void LayoutLabel(CEikLabel* aLabel,
                                     const TRect& aLabelParent,
                                     const TAknMultiLineTextLayout& aLayout,
                                     const CFont *aCustomFont=0);

    /** Layouts a label via a layout compiler output
    @param aLayout   a define from aknlayout.lag file
     */
    IMPORT_C static void LayoutLabel(CEikLabel* aLabel,
                                     const TRect& aLabelParent,
                                     const TAknTextLineLayout& aLayout,
                                     const CFont *aCustomFont=0);

    /** Layouts a label via parameters from the specification
    @param aLayout   a define from aknlayout.lag file
    @param font      font id, ELatinPlain12, ELatinBold12, ELatinBold13, ELatinBold17, ELatinBold19 etc..
    @param C         colour index, 0..255
    @param l         left margin
    @param r         right margin
    @param B         Baseline from top of the parent rectangle
    @param W         text width in pixels
    @param J         justification. ELayoutAlignNone; ELayoutAlignCenter; ELayoutAlignLeft; ELayoutAlignRight; ELayoutAlignBidi
    @param NextLineB baseline of 2nd line for multi-line labels/editors
    @param aCustomFont   a font used, if resource file uses EFontCustom
     */
    IMPORT_C static void LayoutLabel(CEikLabel* aLabel,
                                     const TRect& aLabelParent,
                                     TInt font, TInt C,
                                     TInt l, TInt r,
                                     TInt B, TInt W,
                                     TInt J, TInt NextLineB=0,
                                     const CFont* aCustomFont=0);

    /**
    * Deprecated! Do not use!
    */
    IMPORT_C static void LayoutEdwin(CEikEdwin* aEdwin,
                                     const TRect& aEdwinParent,
                                     TInt aResourceId,
                                     TInt aNumberOfLines = 0,
                                     const CFont* aCustomFont=0,
                                     TBool aMinimizeEdwinView=EFalse);
    /**
    * Deprecated! Do not use!
    */
    IMPORT_C static void LayoutEdwin(CEikEdwin* aEdwin,
                                     const TRect& aEdwinParent,
                                     TResourceReader& aReader,
                                     TInt aNumberOfLines = 0,
                                     const CFont* aCustomFont=0,
                                     TBool aMinimizeEdwinView=EFalse);

    /** Layouts an editor via a structure of layout parameters
    @param aLayout   the structure
     */
    IMPORT_C static void LayoutEdwin(CEikEdwin* aEdwin,
                                     const TRect& aEdwinParent,
                                     const SAknLayoutEdwin& aLayout,
                                     const CFont* aCustomFont=0,
                                     TBool aMinimizeEdwinView=EFalse);

    /** Layouts an editor via a structure of layout parameters
    @param aLayout   the structure
     */

    IMPORT_C static void LayoutEdwin( CEikEdwin* aEdwin,
                                      const TRect& aEdwinParent,
                                      const TAknMultiLineTextLayout& aLayout,
                                      const CFont* aCustomFont=0,
                                      TBool aMinimizeEdwinView=EFalse);

    IMPORT_C static void LayoutEdwin( CEikEdwin* aEdwin,
                                      const TRect& aEdwinParent,
                                      const TAknMultiLineTextLayout& aLayout,
                                      TAknsQsnTextColorsIndex aOverrideColor,
                                      const CFont* aCustomFont=0,
                                      TBool aMinimizeEdwinView=EFalse ); 
        


    IMPORT_C static void LayoutEdwin( CEikEdwin* aEdwin,
                                      const TRect& aEdwinParent,
                                      const TAknTextLineLayout& aLayout,
                                      const CFont* aCustomFont=0,
                                      TBool aMinimizeEdwinView=EFalse );

    IMPORT_C static void LayoutEdwin( CEikEdwin* aEdwin,
                                      const TRect& aEdwinParent,
                                      const TAknTextLineLayout& aLayout,
                                      TAknsQsnTextColorsIndex aOverrideColor,
                                      const CFont* aCustomFont=0,
                                      TBool aMinimizeEdwinView=EFalse );

    /** 
    * Routine to perform standard layout of a CEikEdwin editor.  Two elements from the S60 layout data are required: 
    * The rectangle of the containing layout element, and the TAknTextLineLayout object created for the contained text pane element. 
    * 
    * Override parameters can be supplied for a different number of lines, a different baseline separation,
    * or substituted skin color. Various "Do Not Override" values are to be passed if the values passed in aLayout are to be used. 
    * Refer to the parameters' documentation.
    * 
    * The lower extent of the editor to be laid out (whether driven by the NumberOfLinesToShow() 
    * feature of the TAknTextLineLayout object, or overridden by aNumberOfLinesToShowOverRide)
    * will not extend below the lower limit of the rectangle aEdwinParent.  Thus the number of
    * lines formatted is limited, and is available as an output parameter.
    * 
    * The height of the editor is also restricted by any value previously set in 
    * CEikEdwin::SetMaximumHeightInLines().
    * 
    * @since 3.1 
    * 
    * @param aEdwin          pointer to the editor to be laid out 
    * @param aEdwinParent    rectangle of the containing layout element 
    * @param aLayout         object representing the layout of the text pane implemented by this editor 
    * @param aNumberOfLinesToShowOverride  number of lines overriding aLayout, if not KAknLayoutUtilsDoNotOverride 
    * @param aBaselineSeparationOverride   vertical separation of baselines overriding aLayout, if not KAknLayoutUtilsDoNotOverride 
    * @param aOverrideColor      Avkon Skins color index to override with, if 
    *                            not (TAknsQsnTextColorsIndex)KAknLayoutUtilsDoNotOverride 
    * @param aNumberOfVisibleLines  Number of lines of editor actually laid out.
    */ 
    IMPORT_C static void LayoutEdwin( CEikEdwin* aEdwin,
                         const TRect& aEdwinParent,
                         const TAknTextLineLayout& aLayout,
                         TInt aNumberOfLinesToShowOverRide,
                         TInt aBaselineSeparationOverRide,
                         TAknsQsnTextColorsIndex aOverrideColor, 
                         TInt& aNumberOfVisibleLines );
                                 
    /** Layouts an editor via parameters from the specification
    @param aLayout   a define from aknlayout.lag file
    @param font      font id, ELatinPlain12, ELatinBold12, ELatinBold13, ELatinBold17, ELatinBold19 etc..
    @param C         colour index, 0..255
    @param l         left margin
    @param r         right margin
    @param B         Baseline from top of the parent rectangle
    @param W         text width in pixels
    @param J         justification. ELayoutAlignNone; ELayoutAlignCenter; ELayoutAlignLeft; ELayoutAlignRight; ELayoutAlignBidi
    @param aNumberOfLinesShown number of lines visible for the editor
    @param NextLineB baseline of 2nd line for multi-line labels/editors
    @param aMinimizeEdwinView whether to use minimum size. You need to use MinimizedEdwinRect() if you use ETrue here.
     */
    IMPORT_C static void LayoutEdwin( CEikEdwin* aEdwin,
                                      const TRect& aEdwinParent,
                                      TInt font,
                                      TInt C,
                                      TInt l,
                                      TInt r,
                                      TInt B,
                                      TInt W,
                                      TInt J,
                                      TInt aNumberOfLinesShown,
                                      TInt aNextLineBaseline,
                                      const CFont* aCustomFont=0 ,
                                      TBool aMinimizeEdwinView=EFalse );

    IMPORT_C static void LayoutEdwin( CEikEdwin* aEdwin,
                                      const TRect& aEdwinParent,
                                      TInt font,
                                      TInt C,
                                      TInt l,
                                      TInt r,
                                      TInt B,
                                      TInt W,
                                      TInt J,
                                      TInt aNumberOfLinesShown,
                                      TInt aNextLineBaseline,
                                      TAknsQsnTextColorsIndex aOverrideColor,
                                      const CFont* aCustomFont=0 ,
                                      TBool aMinimizeEdwinView=EFalse );
    /** Use this, if you give aMinimizeEdwinView to LayoutEdwin as true.
     * The edwin will not draw the whole rectangle allocated for the control.
     */
    IMPORT_C static TRect MinimizedEdwinRect(const CEikEdwin *aEdwin);


    /**
    * Deprecated! Do not use!
    */
    IMPORT_C static void LayoutMfne(CEikMfne* aMfne,
                                    const TRect& aMfneParent,
                                    TInt aResourceId);
    /**
    * Deprecated! Do not use!
    */
    IMPORT_C static void LayoutMfne(CEikMfne* aMfne,
                                    const TRect& aMfneParent,
                                    TResourceReader& aReader);

    IMPORT_C static void LayoutMfne(CEikMfne* aMfne,
                                    const TRect& aMfneParent,
                                    const SAknLayoutMfne& aLayout);

    IMPORT_C static void LayoutMfne(CEikMfne* aMfne,
                                    const TRect& aMfneParent,
                                    const TAknTextLineLayout& aLayout);

    IMPORT_C static void LayoutMfne(CEikMfne* aMfne,
                                    const TRect& aMfneParent,
                                    TInt font, TInt C, TInt l, TInt r,
                                    TInt B, TInt W, TInt J);

    /**
    * Deprecated! Do not use!
    */
    IMPORT_C static void LayoutControl(CCoeControl* aControl, 
                                       const TRect& aControlParent,
                                       TInt aResourceId);
    /**
    * Deprecated! Do not use!
    */
    IMPORT_C static void LayoutControl(CCoeControl* aControl,
                                       const TRect& aControlParent,
                                       TResourceReader& aReader);

    IMPORT_C static void LayoutControl(CCoeControl* aControl,
                                       const TRect& aControlParent,
                                       const SAknLayoutControl& aLayout);

    IMPORT_C static void LayoutControl(CCoeControl* aControl, 
                                       const TRect& aControlParent,
                                       const TAknWindowLineLayout& aLayout);

    IMPORT_C static void LayoutControl(CCoeControl* aControl,
                                       const TRect& aControlParent,
                                       TInt /*C*/, TInt l, TInt t, TInt r, TInt b,
                                       TInt W, TInt H);

    /**
    * Deprecated! Do not use!
    */
    IMPORT_C static void LayoutImage(CEikImage* aImage,
                                     const TRect& aParent,
                                     TInt aResourceId);
    /**
    * Deprecated! Do not use!
    */    
    IMPORT_C static void LayoutImage(CEikImage* aImage, 
                                     const TRect& aParent,
                                     TResourceReader& aReader);

    IMPORT_C static void LayoutImage(CEikImage* aImage, 
                                     const TRect& aParent,
                                     const SAknLayoutControl& aLayout);

    IMPORT_C static void LayoutImage(CEikImage* aImage,
                                     const TRect& aParent,
                                     const TAknWindowLineLayout& aLayout);

    IMPORT_C static void LayoutImage(CEikImage* aImage,
                                     const TRect& aParent,
                                     TInt C, TInt l, TInt t, TInt r, TInt b,
                                     TInt W, TInt H);

    /** Sets CEikSecretEditor's position, colors and fonts based on LAF specification
     *
     */
    IMPORT_C static void LayoutSecretEditor(CEikSecretEditor* aSecEd,
                                            const TRect& aParent,
                                            const SAknLayoutText& aLayout);

    IMPORT_C static void LayoutSecretEditor(CEikSecretEditor* aSecEd,
                                            const TRect& aParent,
                                            const TAknTextLineLayout& aLayout);

public:
    /** Different conversions
     * Fonts: ELatinPlain12, ELatinBold12, ELatinBold13, ELatinBold17, ELatinBold19, ENumberPlain5, EClockBold30, ELatinClock14, EFontCustom
     *        EAknLogicalFontPrimaryFont, EAknLogicalFontSecondaryFont, EAknLogicalFontTitleFont,
     * Alignments: ELayoutAlignNone, ELayoutAlignCenter, ELayoutAlignLeft, ELayoutAlignRight, ELayoutAlignBidi with these..
     */
    IMPORT_C static TRect TextRectFromCoords(const TRect& aParent,
                                             const CFont* aFont,
                                             TInt l, TInt r,
                                             TInt B, TInt W,
                                             TInt LB = 0);

    IMPORT_C static TRect RectFromCoords(const TRect& aParent,
                                         TInt l, TInt t, TInt r, TInt b,
                                         TInt W, TInt H);

    /**
    * Method to return a useable system font reference from a S60 font enumeration from among
    * the supported list.
    * 
    * This method should only be used if application code needs to render its own graphics. That is, it
    * is not using S60 controls and furthermore not using the recommended methods 
    * AknLayoutUtils::LayoutEdwin(), AknLayoutUtils::LayoutLabel() or AknLayoutUtils::LayoutSecretEditor(). 
    * 
    * Fonts returned by this are not recommended to be stored in clients' member data, but should be
    * accessed when they are required for use.
    *
    * Applications that are written to run with their layout dynamically adapting to different screen sizes 
    * should use only the values found in the S60 logical font enumeration, TAknLogicalFontId.
    * 
    * @param aFontId        Input S60 font id.
    * @param aCustomFont    Font to return if aFontId is given as EFontCustom
    * @return               const pointer to a system font, or aCustomFont
    */
    IMPORT_C static const CFont* FontFromId(TInt aFontId, const CFont* aCustomFont=0);

    /**
    * Method to return a system font reference from a S60 font id. This will always conform to type CAknLayoutFont
    * 
    * This method should only be used if application code needs to render its own graphics. That is, it
    * is not using S60 controls and furthermore not using the recommended methods 
    * AknLayoutUtils::LayoutEdwin(), AknLayoutUtils::LayoutLabel() or AknLayoutUtils::LayoutSecretEditor(). 
    * 
    * Fonts returned by this are not recommended to be stored in clients' member data, but should be
    * accessed when they are required for use.
    *
    * Applications that are written to run with their layout dynamically adapting to different screen sizes 
    * should use only the values found in the S60 logical font enumeration, TAknLogicalFontId.
    * 
    * @param aFontId        Input S60 font id.
    * @param aCustomFont    Font to return if aFontId is given as EFontCustom
    * @return               const pointer to a system font, or aCustomFont
    */
    IMPORT_C static const CAknLayoutFont* LayoutFontFromId(TInt aId, 
                                                           const CAknLayoutFont *aCustomFont = 0);

    /**
    * Return a fully constructed CAknLayoutFont object based upon the specification passed in.
    * The Avkon font specifiation object uses TAknFontCategory to determine the font. 
    *
    * The font object is returned as non-const, since it is owned and will eventually be deleted by the client.
    * 
    * @param aSpec     S60 font specification object
    * @return               pointer to a CAknLayoutFont object, owned by the caller
    */
    IMPORT_C static CAknLayoutFont* CreateLayoutFontFromSpecificationL( 
        const TAknFontSpecification& aSpec );

    /**
    * Return a fully constructed CAknLayoutFont object based upon the typeface and specification passed in.
    * The TTypeface object contains a typeface name that is used as the primary key to select a font.  
    * The S60  font specifiation object is also used, but any value of TAknFontCategory passed in is reset to 
    * EAknFontCategoryUndefined, and is not used to select the font. 
    *
    * The font object is returned as non-const, since it is owned and will eventually be deleted by the client.
    * 
    * @param aTypeface      Symbian Typface object
    * @param aSpec             S60 font specification object
    * @return                       pointer to a CAknLayoutFont object, owned by the caller
    */
    IMPORT_C static CAknLayoutFont* CreateLayoutFontFromSpecificationL( 
        const TTypeface& aTypeface, 
        const TAknFontSpecification& aSpec);

    /**
    * Deprecated! Do not use!
    */
    IMPORT_C static const CFont* FontFromName(const TDesC& aName); 

    IMPORT_C static CGraphicsContext::TTextAlign TextAlignFromId(TInt aId);

    IMPORT_C static TGulAlignment GulAlignFromId(TInt aId);

    IMPORT_C static TInt CursorHeightFromFont(const TFontSpec& aFont);

    IMPORT_C static TInt CursorWidthFromFont (const TFontSpec& aFont);

    IMPORT_C static TInt CursorAscentFromFont(const TFontSpec& aFont);

    IMPORT_C static void CursorExtensionsFromFont(const TFontSpec& /*aFont*/,
                                                  TInt& aFirstExtension,
                                                  TInt& aSecondExtension);

    IMPORT_C static TInt HighlightLeftPixelsFromFont (const TFontSpec& aFont);

    IMPORT_C static TInt HighlightRightPixelsFromFont(const TFontSpec& aFont);
    static void HighlightExtensionsFromFont(const TInt fontid,
                                            TInt& aLeft, TInt& aRight,
                                            TInt&  aTop, TInt& aBottom);

    /**
    * Access the system font array to see if there is a font that matches the  
    * font specification presented in Twips. Device map is also passed in case the 
    * system font array has fonts from different devices.
    * 
    * A null return value means that the system font array is not constructed yet, or does
    * not contain a font that has the same TFontSpec or device map.
    *
    * @param aSpec  Symbian font specification object to match
    * @param aMap   Device map to disambiguate fonts on different devices
    * @return       NULL if no match was found; otherwise a CAknLayoutFont pointer
    **/
    static const CAknLayoutFont* MatchFontFromSystemFontArray( 
        const TFontSpec& aSpec, MGraphicsDeviceMap* aMap );

    IMPORT_C static TBool LayoutMirrored();

    /*
    * This method returns build variant based on which flag is active,
    * __AVKON_ELAF__ or __AVKON_APAC__.
    *
    * If you need to decide which layout to use, do not do it based on this method.
    * Instead, use CAknEnv::GetCurrentLayoutId().
    *
    * @return current variant
    */
    IMPORT_C static EVariantFlag Variant();

    IMPORT_C static ESubVariantFlag SubVariant();

    IMPORT_C static void OverrideControlColorL(
        CCoeControl& aControl,
        TLogicalColor aLogicalColor,
        TRgb aColor);
    
    /*
    * This method returns the default scrollbar type for the given application. 
    * For non-layout aware applications (e.g. legacy apps designed for 176x208 screen) 
    * this method returns always EArrowHead. But for layout aware apps the returned type 
    * may vary depending on the type of scrollbar which has been set as preferred 
    * scrollbar type in the device.
    *
    * Note that applications may use freely whatever scrollbartype, this method only 
    * returns the default scrollbartype for the application.
    * 
    * @since  2.6
    * @param  aApplication Application of which default scrollbar type is requested.
    * @return Default scrollbar type for the given application
    */
    IMPORT_C static CEikScrollBarFrame::TScrollBarType DefaultScrollBarType(CAknAppUiBase* aApplication);

    /*
    * This method sets the layout for vertical scrollbar of the given scrollbar frame. Layout
    * can freely only be set for EDoubleSpan type scrollbars.
    * 
    * @since  2.6
    * @param  aScrollBarFrame   Scrollbarframe of which vertical scrollbar layout will be set.
    * @param  aControlParent    Rect of the parent control of the scrollbarframe.
    * @param  aLayout           Layout for the vertical scrollbar.
    *
    *
    * This method can also be useful when layout of the scrollbar needs to be changed for scrollbars
    * which are owned by some other components such as e.g. ListBoxes, Editors or Grids.
    *
    * Example of use:
    *
    *  // Get a pointer to scrollbarframe of the listbox
    *  CEikScrollBarFrame* frame = iListBox->ScrollBar();
    *  
    *  // Get the layout data
    *  TAknWindowLineLayout layout = GetMyListBoxLayout();
    *  Trect parentRect = GetMyListBoxParentRect();
    *
    *  // Set the layout
    *  AknLayoutUtils::LayoutVerticalScrollBar(frame, parentRect, layout);
    *
    *  // The layout for scrollbar is now set.
    *
    */
    IMPORT_C static void LayoutVerticalScrollBar(
        CEikScrollBarFrame* aScrollBarFrame,
        const TRect& aControlParent,
        const TAknWindowLineLayout& aLayout);

    /*
    * This method sets the layout for horizontal scrollbar of the given scrollbar frame. Layout
    * can freely only be set for EDoubleSpan type scrollbars.
    * 
    * @since  2.6
    * @param  aScrollBarFrame   Scrollbarframe of which horizontal scrollbar layout will be set.
    * @param  aControlParent    Rect of the parent control of the scrollbarframe.
    * @param  aLayout           Layout for the horizontal scrollbar.
    *
    *
    * Usage of this method is similar as for LayoutVerticalScrollBar().
    *
    */
    IMPORT_C static void LayoutHorizontalScrollBar(
        CEikScrollBarFrame* aScrollBarFrame,
        const TRect& aControlParent,
        const TAknWindowLineLayout& aLayout);

public:   // Metrics API

    /**
    * Layout Metrics.
    */
    enum TAknLayoutMetrics
    {
        /** Screen. */
        EScreen,
        
        /** Window that fills the entire screen. */
        EApplicationWindow,
        
        /** Indicates common components for most of the applications. */
        EStatusPane,
        
        /** The application main pane is used in all the applications */
        EMainPane,
        
        /** Control pane. */
        EControlPane,   
        
        /** The signal pane is used to indicate signal strength. */
        ESignalPane,
        
        /** The context pane is used to indicate an active application. */
        EContextPane,
        
        /** Used to indicate the subject or the name of the main pane content.*/
        ETitlePane,
        
        /** The battery pane is used to indicate battery strength. */
        EBatteryPane,
        
        /** 
         * The universal indicator pane is used to indicate items that require
         * the user's attention while browsing applications.
         */
        EUniversalIndicatorPane,
        
        /** 
         * The navi pane is used to indicate navigation within an application,
         * to provide context sensitive information to the user while entering
         * or editing data, or to show additional information.
         */
        ENaviPane,
        
        /** 
         * A fixed find pane is used with lists instead of the find pop-up
         * window. */
        EFindPane,
        
        /** Wallpaper pane. */
        EWallpaperPane,
        
        /** 
         * The universal indicator pane is used to indicate items that require
         * the user's attention while browsing applications.
         */
        EIndicatorPane,
        
        /** Used generally to display small sized graphics or heading texts. */
        EAColunm,
        
        /** Used generally to display large sized icons or heading texts. */
        EBColunm,
        
        /** 
         * Used generally to display data entered by the user. Overlaps with
         * the D column.
         */
        ECColunm,
        
        /** 
         * Used generally to display additional icons. Overlaps with
         * the C column.
         */
        EDColunm,
        
        /** @deprecated, do not use */
        EStatusPaneSecondary,
        
        /** deprecated, do not use */
        EControlPaneSecondary,
        
        /** Top part of status and control panes in landscape layout. */
        EStaconTop,
        
        /** Bottom part of status and control panes in landscape layout. */
        EStaconBottom,

        /** */
        EPopupParent,
        
        /** Bottom part of status pane in landscape layout. */
        EStatusPaneBottom = EStatusPaneSecondary,
        
        /** Bottom part of control pane in landscape layout. */
        EControlPaneBottom = EControlPaneSecondary,
        
        /** Top part of control pane in landscape layout. */
        EControlPaneTop = EControlPane,
        
        /** Top part of status pane in landscape layout. */
        EStatusPaneTop = EStatusPane
    };


    /**
    * Fills given TRect with rectangle for given layout component. 
    * Returns EFalse for status pane descendants if requested
    * layout component is not available in current layout. For
    * other components returns always ETrue (returned rectangle is
    * from layout definition).
    *
    * @since  2.8
    * @param  aParam   Layout component to be queried. 
    * @param  aRect    Resulting rectangle.
    * @param  ETrue    If requested value was available.
    *         EFalse   Otherwise.
    */
    IMPORT_C static TBool LayoutMetricsRect(TAknLayoutMetrics aParam, TRect& aRect);

    /**
    * This method returns size of rectangle for given layout component.
    * Returns EFalse for status pane descendants if requested
    * layout component is not available in current layout. For
    * other components returns always ETrue (returned size is
    * from layout definition).
    *
    * @since  2.8
    * @param  aParam   Layout component to be queried. 
    * @param  aSize    Resulting size.
    * @param  ETrue    If requested value was available.
    *         EFalse   Otherwise.
    */
    IMPORT_C static TBool LayoutMetricsSize(TAknLayoutMetrics aParam, TSize& aSize);

    /**
    * This method returns position of top left corner for given layout component.
    * Returns EFalse for status pane descendants if requested
    * layout component is not available in current layout. For
    * other components returns always ETrue (returned position is
    * from layout definition).
    *
    * @since  2.8
    * @param  aParam   Layout component to be queried. 
    * @param  aPos     Resulting position.
    * @param  ETrue    If requested value was available.
    *         EFalse   Otherwise.
    */
    IMPORT_C static TBool LayoutMetricsPosition(TAknLayoutMetrics aParan, TPoint& aPos);
public:
    /**
    * This method returns a new value for a baseline, based upon a value for bottom and 
    * a value for height. For legacy layout data, the baseline will be correct, and this
    * method will detect that it is a legacy font id and just return aBottom. 
    * However, for scalable layout data, the bottom value will be hidden inside 
    * the old baseline variable, so call this method passing in 'iB', NOT passing in 'ib'
    * ... e.g.: (the following line is an example, so is ok to have commented out code)
    * TInt newbaseline = CorrectBaseline(myLayoutLine.iB, myLayoutLine.iFont);
    *
    * @since  2.8
    * @param  aBottom  Baseline or Bottom value of text pane (found in TAknTextLineLayout.iB)
    * @param  aFontId     FontId of text pane (for scalable layouts, this will encode the height)
    * @return   new Baseline value
    */
    static TInt CorrectBaseline(TInt aParentHeight, TInt aBaseline, TInt aFontId);

    /**
    * This method updates fontid if it has ELayoutEmpty or parent relative values
    */
    static void CorrectFontId(TRect aParent, TInt at, TInt aH, TInt ab, TInt &aFontId);

    /**
    * This method tells if the scalable layout interface is available.
    * 
    * @internal
    * @return ETrue if scalable layout interface can be used, otherwise EFalse.
    */
    IMPORT_C static TBool ScalableLayoutInterfaceAvailable();
    
    /*
    * Enumeration of CBA's possible locations.
    * @since 3.0
    */
    enum TAknCbaLocation
        {
        EAknCbaLocationBottom, //landscape and portrait
        EAknCbaLocationRight,  //only landscape
        EAknCbaLocationLeft    //only landscape
        };
    
    /**
    * This method tells location of softkeys (CBA) field in current running application. 
    * Possible location of softkeys are bottom (portrait and landscape), left and right 
    * (only landscape).
    *
    * @since 3.0
    * @return TAknCbaLocation
    */
    IMPORT_C static TAknCbaLocation CbaLocation();

    /**
    * Used by pop-ups to align themselves around the given highlighted area.
    * @param aHighlightRect Highlighted area.
    * @param aControl Control whose position should be calculated,
    * @return TRect Size and position of pop-up.
    */
    static TRect HighlightBasedRect( const TRect& aHighlightRect, CCoeControl* aControl );

    /**
     * Flags for main_pane status
     */
    enum TAknMainPaneState 
        {
        EAknMainPaneForTinyStatusPane = 0x0001  // for 3x4 grid or app shell list views
        };
    IMPORT_C static TAknMainPaneState MainPaneState();

    /**
    * This method can be used to check whether pen support is enabled.
    * @return ETrue if pen support is enabled, otherwise EFalse.
    */
    IMPORT_C static TBool PenEnabled();
    
    /**
    * This method can be used to check whether MSK support is enabled.
    * @return ETrue if MSK support is enabled, otherwise EFalse.
    */
    IMPORT_C static TBool MSKEnabled();

    /**
    * Utility method to be used along side LayoutEdwin methods that take number of lines or 
    * baseline separation overrides. 
    * 
    * This routine returns the edwin height in pixels required to fit exactly the passed-in layout,
    * or the layout with overridden baseline separation and/or number of lines.
    * 
    * The vertical position of the editor is also returned. Note that the correct
    * height of the parent layout item is needed in order for this to be calculated properly.
    *
    * Note that this API does not cause a layout of the editor.
    * 
    * @since 3.1
    *
    * @param aParentHeight  Height of the parent layout item
    * @param aLayout        S60 layout object for the text to be laid out in the editor
    * @param aBaselineSeparationOverride   vertical separation of baselines overriding aLayout, if not KAknLayoutUtilsDoNotOverride 
    *                                       aLayout, if not KAknLayoutUtilsDoNotOverride 
    * @param aNumberOfLinesToShowOverride   number of lines overriding aLayout, 
    *                                       if not KAknLayoutUtilsDoNotOverride 
    * @param aEdwinVerticalPositionRelativeToParent     Returns the vertical postion of the editor 
    *                                                   relative to its parent when laid out.
    * @param aEdwinHeight   The height required in pixels to fit the required number of laid 
    *                       out lines plus highlights.
    */
    IMPORT_C static void GetEdwinVerticalPositionAndHeightFromLines(
        TInt aParentHeight,
        const TAknTextLineLayout& aLayout,
        TInt aBaselineSeparationOverRide,
        TInt aNumberOfLinesToShowOverRide,
        TInt& aEdwinVerticalPositionRelativeToParent,
        TInt& aEdwinHeight
        );
       
    /**
    * Utility routine to give the number of text lines that will completely fit, 
    * including room for highlights, within the given height, when the passed in layout is
    * being used. 
    *
    * Note that the NumberOfLinesShown() value from the TAknTextLineLayout object is not taken into
    * consideration. This routine ignores it, and returns number of lines based upon the font metrics,
    * hightlight specification, and the passed in maximum height.
    * 
    * Note that this API does not cause a layout of the editor.
    *
    * @since 3.1
    *
    * @param aLayout    S60 layout object for the text to be laid out in the editor    
    * @param aBaselineSeparationOverride   vertical separation of baselines 
    *       overriding aLayout, if not KAknLayoutUtilsDoNotOverride 
    * @param aMaxHeight     Input maximum height to use for the editor.
    * @param aUsedHeight    Returns the number of pixels required for the lines that fit
    * @return The number of lines which completely fit
    */
    IMPORT_C static TInt EdwinLinesWithinHeight (
        const TAknTextLineLayout& aLayout,
        TInt aBaselineSeparationOverride,
        TInt aMaxHeight,
        TInt& aUsedHeight
        );
};

/** Low level drawing based on European LAF document (can be used by application's custom controls)
 *
 * This class reads AVKON_LAYOUT_TEXT resources
 */
class TAknLayoutText
    {
public:
    IMPORT_C TAknLayoutText();
    /** Read resources and calculate information needed to draw text.
     *
     * LayoutText() call should be placed to control's SizeChanged() method.
     */
    IMPORT_C void LayoutText(const TRect& aParent, TInt aResourceId,
                             const CFont* aCustomFont=0);

    IMPORT_C void LayoutText(const TRect& aParent, TResourceReader& aReader,
                             const CFont* aCustomFont=0);

    IMPORT_C void LayoutText(const TRect& aParent, 
                             const AknLayoutUtils::SAknLayoutText& aLayout,
                             const CFont* aCustomFont=0);

    IMPORT_C void LayoutText(const TRect& aParent,
                             const TAknTextLineLayout& aLayout,
                             const CFont* aCustomFont=0);

    IMPORT_C void LayoutText(const TRect& aParent, TInt fontid, 
                             TInt C, TInt l, TInt r, TInt B, TInt W, TInt J,
                             const CFont* aCustomFont=0);

    /** Do the actual drawing, should be placed to control's Draw() method.
     */
    IMPORT_C void DrawText(CGraphicsContext& aGc, const TDesC& aText) const;
    
    /**
    * In case of bidirectional text, which is already converted from logical to
    * visual order, use this method with parameter 
    * aUseLogicalToVisualConversion EFalse.
    */
    IMPORT_C void DrawText(
        CGraphicsContext& aGc,
        const TDesC& aText,
        TBool aUseLogicalToVisualConversion ) const;

    IMPORT_C void DrawText(
        CGraphicsContext& aGc,
        const TDesC& aText,
        TBool aUseLogicalToVisualConversion,
        const TRgb &aColor) const;
                           

public:
    /** This returns rectangle that is used to draw the text.
     *
     * This allows you to divide screen space for egul's TextUtils::ClearBetweenRect()
     * without knowing exact coordinates => when coordinates change, your code 
     * does not need to change.
     */
    IMPORT_C TRect TextRect() const;
    const CFont *Font() const { return iFont; }
    TRgb Color() const { return AKN_LAF_COLOR_STATIC(iColor); }
    CGraphicsContext::TTextAlign Align() const { return iAlign; }
    /**
    * Returns the baseline position for the font set in this object.
    * This value, together with TextRect(), are the metrics that are used to 
    * parametrise a call to DrawText, for example:
    *      void CGraphicsContext::DrawText( 
    *            const TDesC& aText, 
    *            const TRect& aBox, 
    *            TInt aBaselineOffset, 
    *            TTextAlign aAlignment = ELeft,
    *            TInt aLeftMargin = 0);
    * 
    *  TAknLayoutText's own DrawText methods are recommended, however.
    * 
    *  Notice that this value is relative to the top of the TextRect() rectangle, 
    *  which is generally made to bound all accents. Thus this offset value 
    *  is usually larger than the CFont::AscentInPixels value.
    * 
    * @since 3.1 
    * @return   distance in pixels measured from the top of the textpane down to the baseline
    */
    TInt BaselineOffset() const;
private:
    TRect iTextRect;
    const CFont *iFont; // not owned..
    TInt iColor;
    TInt iOffset;
    CGraphicsContext::TTextAlign iAlign;
    friend class CBubbleOutlookNumberEntry;
    };

/** Low level rectangle management based on European LAF document (can be used by application's custom controls)
 * 
 * This allows you to draw images, rectangles, lines or just calculate rectangles based on LAF spec.
 *
 * This class reads AVKON_LAYOUT_RECT resources.
 *
 * Instances of this class should be placed inside controls for reading low level layout from resources.
 */
class TAknLayoutRect
    {    
public:
    IMPORT_C TAknLayoutRect();
    /** LayoutRect should be called from control's SizeChanged() method.
     */
    IMPORT_C void LayoutRect(const TRect &aParent, TInt aResourceId);
    IMPORT_C void LayoutRect(const TRect &aParent, TResourceReader &aReader);
    IMPORT_C void LayoutRect(const TRect &aParent, 
                             const AknLayoutUtils::SAknLayoutRect &aLayout);

    IMPORT_C void LayoutRect(const TRect &aParent,
                             const TAknWindowLineLayout &aLayout);

    IMPORT_C void LayoutRect(const TRect &aParent, 
                             TInt C, TInt l, TInt t, TInt r, TInt b,
                             TInt W, TInt H);
    
    /** Color() can be called from control's Draw() method. 
    
    DO NOT CALL it in SizeChanged(), ConstructL() or ActivateL() method, because 
    it messes up color scheme changes. Especially if you're using colors 226-248.
    If you store color values, be prepared to update TRgb's you store when color
    palette is changed! Best thing to do is to make your Draw() methods call
    AKN_LAF_COLOR().
     */    
    IMPORT_C TRgb Color() const;
    /** Rect() can be called from control's Draw() or in SizeChanged() as input for some other table's layout code.
     */
    IMPORT_C TRect Rect() const;
    TBool Valid() const;

    /** DrawRect() and DrawImage() should be called from control's Draw() method.
     */
    IMPORT_C void DrawRect(CWindowGc& aGc) const;
    IMPORT_C void DrawOutLineRect(CWindowGc& aGc) const;
    IMPORT_C void DrawImage(CBitmapContext& aGc, CFbsBitmap* aBitmap, CFbsBitmap* aMask) const;
private:
    TInt iColor;
    TRect iRect;
    };

/**
 * Helper functions for drawing empty lists and window shadows
 */
class AknDraw 
    {
public:
    /** 
    Draws standard empty list
    @param aRect the client rectangle
    @param aGc   the graphics context
    @param aText text for empty list in format "Line1\nLine2"
     */
    IMPORT_C static void DrawEmptyList(
        const TRect& aRect,
        CWindowGc& aGc,
        TPtrC aText);

    /** 
    Draws empty list for setting item editing
    @param aRect the rectangle of setting page's content
    @param aGc   the graphics context
    @param aText text for empty list in format "Line1\nLine2"
     */
    IMPORT_C static void DrawEmptyListForSettingPage(
        const TRect &aRect,
        CWindowGc &aGc,
        TPtrC text); // only for setting page with empty layout.

    /** 
    Draws empty list for lists with find
    @param aRect the client rectangle
    @param aGc   the graphics context
    @param aText text for empty list in format "Line1\nLine2"
     */
    IMPORT_C static void DrawEmptyListWithFind(
        const TRect& aClientRect,
        CWindowGc& aGc,
        TPtrC aText); // only for fixed find pane used with single graphics listbox.

    /** 
    Draws empty list for lists with heading
    @param aRect the client rectangle
    @param aGc   the graphics context
    @param aText text for empty list in format "Line1\nLine2"
     */
    IMPORT_C static void DrawEmptyListHeading(
        const TRect &aClientRect,
        CWindowGc& aGc,
        TPtrC aText); // only heading style lists.

    // The following is optimization for drawing window shadows.
    /** 
    Draws a window shadow
    @param aCoverRect the area covered by the shadow
    @param aSecondShadowRect the area used for second shadow
    @param aFirstShadowRect  the area of first shadow
    @param aOutliineFrameRect the area of black outline frame
    @param aInsideAreaRect   the area of content inside the window
     */
    IMPORT_C static void DrawWindowShadow(
        CWindowGc& aGc,
        const TAknLayoutRect& aCoverRect,
        const TAknLayoutRect& aSecondShadowRect,
        const TAknLayoutRect& aFirstShadowRect,
        const TAknLayoutRect& aOutlineFrameRect,
        const TAknLayoutRect& aInsideAreaRect);

public:

    /** 
    * The main implementation routine for empty list drawing.
    * @param aRect the client rectangle
    * @param aGc   the graphics context
    * @param aText text for empty list in one of following formats:
    *
    * layouts with large font:
    * "Line 1"
    * "Long line. This will be wrapped to 2 lines and 2nd will be trunca..."
    * "Line 1\nLine 2"
    *
    * layout with 1 line of large font and up to 3 lines with small font:
    * "Line 1\nLong line, will be wrapped up to 3 lines with small font and..."
    *
    *
    * @param aLayoutLine1 Resource id of AVKON_LAYOUT_TEXT for first line layout 
    * @param aLayoutLine2 Resource id of AVKON_LAYOUT_TEXT for second line layout 
     */
    IMPORT_C static void DrawEmptyListImpl( const TRect& aRect,
                                            CWindowGc& aGc,
                                            TPtrC aText,
                                            TInt aLayoutLine1,
                                            TInt aLayoutLine2 );
    
    };

/**
 * Helper functions for drawing empty lists and window shadows
 */
class AknDrawWithSkins
    {
public:
    /** 
    Draws standard empty list
    @param aRect the client rectangle
    @param aGc   the graphics context
    @param aText text for empty list in format "Line1\nLine2"
     */
    IMPORT_C static void DrawEmptyList(
        const TRect& aRect,
        CWindowGc& aGc,
        TPtrC aText,
        CCoeControl *aControl);

    /** 
    Draws empty list for setting item editing
    @param aRect the rectangle of setting page's content
    @param aGc   the graphics context
    @param aText text for empty list in format "Line1\nLine2"
     */
    IMPORT_C static void DrawEmptyListForSettingPage(
        const TRect &aRect,
        CWindowGc &aGc,
        TPtrC text,
        CCoeControl *aControl); // only for setting page with empty layout.

    /** 
    Draws empty list for lists with find
    @param aRect the client rectangle
    @param aGc   the graphics context
    @param aText text for empty list in format "Line1\nLine2"
     */
    IMPORT_C static void DrawEmptyListWithFind(
        const TRect& aClientRect,
        CWindowGc& aGc,
        TPtrC aText,
        CCoeControl *aControl); // only for fixed find pane used with single graphics listbox.

    /** 
    Draws empty list for lists with heading
    @param aRect the client rectangle
    @param aGc   the graphics context
    @param aText text for empty list in format "Line1\nLine2"
     */
    IMPORT_C static void DrawEmptyListHeading(
        const TRect &aClientRect,
        CWindowGc& aGc,
        TPtrC aText,
        CCoeControl *aControl); // only heading style lists.

    // The following is optimization for drawing window shadows.
    /** 
    Draws a window shadow
    @param aCoverRect the area covered by the shadow
    @param aSecondShadowRect the area used for second shadow
    @param aFirstShadowRect  the area of first shadow
    @param aOutliineFrameRect the area of black outline frame
    @param aInsideAreaRect   the area of content inside the window
     */
    IMPORT_C static void DrawWindowShadow(
        CWindowGc& aGc,
        const TAknLayoutRect& aCoverRect,
        const TAknLayoutRect& aSecondShadowRect,
        const TAknLayoutRect& aFirstShadowRect,
        const TAknLayoutRect& aOutlineFrameRect,
        const TAknLayoutRect& aInsideAreaRect,
        CCoeControl *aControl);
    
    };




// Browser and calculator fonts will not be placed here. Application
// can use them themselves with CEikonEnv::Static()->Font() call.
IMPORT_C const CFont *LatinPlain12();
IMPORT_C const CFont *LatinBold12();
IMPORT_C const CFont *LatinBold13();
IMPORT_C const CFont *LatinBold16(); // since 2.0
IMPORT_C const CFont *LatinBold17();
IMPORT_C const CFont *LatinBold19(); 
IMPORT_C const CFont *NumberPlain5();
IMPORT_C const CFont *ClockBold30();
IMPORT_C const CFont *LatinClock14();
const CFont *CalcBold21();
const CFont *CalcOperBold21();
const CFont *CalcOperBold13();



IMPORT_C const CFont *ApacPlain12();
IMPORT_C const CFont *ApacPlain16();


/**
* CompletePathWithAppPath
*   All the components that are specified in the given descriptor (drive letter,
*   path and file name, including extension) are put into the result;
*   any missing components (path and drive letter) are taken from the app's path.
*
*   Can be used e.g. to load a bitmap file when an application don't know where
*   it has been installed.
*
*   Example1:
*        TFilename fname = _L("\testdir\pics.mbm"); // Use _LIT instead
*        CompletePathWithAppPath( fname );
*        Result:
*            fname == "c:\testdir\pics.mbm" if application was installed to c:
*
*   Example2:
*        TFilename fname = _L("pics.mbm"); // Use _LIT instead
*        CompletePathWithAppPath( fname );
*        Result:
*            fname == "c:\system\apps\myapp\pics.mbm" if application was 
*                installed to c:\system\apps\myapp
*
* @param    aFileName   FileName which will be completed with application's path
* @return   Error code if an error occured. In case of an error aFileName will
*               not be changed
*/
IMPORT_C TInt CompleteWithAppPath( TDes& aFileName );

/**
 * Test whether the value falls within the parent relative range
 * as defined in AknLayout2Def.h
 *
 * @since 2.8
 * @param aVal value
 * @return ETrue if value is within the parent relative range, EFalse otherwise
 */
TBool IsParentRelative(TInt aVal);

/**
 * Returns default input language that corresponds to the UI language.
 *
 * @since 3.0
 * @param aUiLanguage Language code of the UI language
 * @return Language code of the default input language
 */
IMPORT_C TInt DefaultInputLanguageFromUILanguage(const TInt aUiLanguage);

    /**
    * Sets the key block mode.
    * Has the same functionality as SetKeyBlockMode in AknAppUi,
    * but this can be used from a non app-framework application.
    * The default mode blocks simultaneous key presses.
    * @param aMode @c ENoKeyBlock if no key block, otherwise
    * @c EDefaultBlockMode
    */
IMPORT_C void SetKeyblockMode( TAknKeyBlockMode aMode );

namespace AknDateTimeUtils
    {
    /**
    * Converts given UTC time to home time.
    * This conversion is used e.g. when showing time stamps of files in UI.
    * In Symbian OS file system, time stamps are in UTC time, but in UI
    * they should be shown in home time.
    *
    * @param aTime UTC time to be converted to home time.
    * @since 3.1
    */
    IMPORT_C void ConvertUtcTimeToHomeTime( TTime& aTime );
    }

#define KAknLanguageMask 0x3FF
#define KAknDialectMask 0xFC00

namespace AknLangUtils
    {
    /**
    * Returns the RFC 3066 tag of the current display language.
    * @since 3.1
    * @ret RFC 3066 tag, ownership transferred to the caller.
    */
    IMPORT_C HBufC* DisplayLanguageTagL();
    
    TLanguage UserLanguage();
    
    }

/**
 * Helper functions for Popups
 * 
 * @since S60 v5.2
 */
class AknPopupUtils
    {
public:
    /** 
     * Calculates proper position for a popup control. Returned value depends
     * on currently active layout and softkey visibility.
     * 
     * @param aSize             The size of the popup.
     * @param aSoftkeysVisible  ETrue if softkeys are visible.
     * @return                  Corrent popup position.
     */
    IMPORT_C static TPoint Position( const TSize& aSize,
        TBool aSoftkeysVisible );

    /** 
     * Calculates proper position for a popup control. Returned value depends
     * on currently active layout and softkey visibility which is checked from
     * aControl via MOP chain.
     * 
     * @param aSize         The size of the popup.
     * @param aControl      Control who's position should be calculated.
     * @return              Corrent popup position.
     */
    IMPORT_C static TPoint Position( const TSize& aSize,
        CCoeControl* aControl );
    };


/**
 * Helper functions for Lists
 * 
 * @since S60 v5.2
 */
class AknListUtils
    {
public:
    /** 
     * Draws a separator line between list items.
     * 
     * @param aGc       Graphics context where separator is drawn to.
     * @param aRect     Rectangle occupied by the item that is separated.
     * @param aColor    Text color used in item. Separator is drawn with this
     *                  color and additional alpha mask.
     * @param aSkin		Skin instance used to get the alpha value
     *                  for the separator line color.
     */
    IMPORT_C static void DrawSeparator( CGraphicsContext& aGc, 
                                        const TRect& aRect,
                                        const TRgb& aColor,
                                        MAknsSkinInstance* aSkin = NULL );
    };

#endif //  __AKNUTILS_H__

// End of file

