diff -r e1b950c65cb4 -r 837f303aceeb epoc32/include/mw/AknUtils.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/epoc32/include/mw/AknUtils.h Wed Mar 31 12:33:34 2010 +0100 @@ -0,0 +1,2727 @@ +/* +* Copyright (c) 2002-2007 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of "Eclipse Public License v1.0" +* which accompanies this distribution, and is available +* at the URL "http://www.eclipse.org/legal/epl-v10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: +* General Avkon Utilities. Includes: +* - listbox utilities +* - layout utilities +* +* +*/ + + +#ifndef __AKNUTILS_H__ +#define __AKNUTILS_H__ + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +// These are for listbox column lengths (These are used to allocate memory from stack while drawing listboxes, they should be as small as possible, but not smaller!) +const TInt KMaxColumnDataLength = 80; // This is maximum length of data for one listbox column -- after that the data is truncated before drawing. +const TInt KMaxTotalDataLength = 8*KMaxColumnDataLength; // max of 5 columns can have full 80 characters... + +/** AVKON utility module + * + * From this file, you can find several tools for making application development easier for S60 + * + * 1) Conversion modules to convert coordinate data from european LAF to usable formats + * AknLayoutUtils, TAknLayoutRect, TAknLayoutText + * 2) Utilities to clip text + * 3) Part of selection service implementation + * 4) Different classes that help using listboxes + * 5) Handling colors in AKN_LAF_COLOR macro. + * 6) Resource readers for different purposes + * 7) Utility to find files without specifying the drive letter or path + */ + + +class CCoeControl; +class CEikTextListBox; +class CEikColumnListBox; +class CEikFormattedCellListBox; +class CGulIcon; +class CEikSettingsListBox; +class CAknLAF; +class CEikImage; +class CEikMfne; +class CEikListBox; +class CEikLabel; +class CEikEdwin; +class CEikMenuPane; +class CAknPopupField; +class CListBoxView; +class CAknColumnListBox; +class CEikSecretEditor; +class CFindExtension; +class CAknLayoutFont; +class TAknFontSpecification; +class CAknAppUiBase; +class TAknWindowLineLayout; +class TAknMultiLineTextLayout; +class TAknTextLineLayout; + +/** + * Egul library had methods to clip text from right side, this class includes methods to clip from both sides. + * It does add 3 dots to the end of the text. + */ +const TInt KDefaultClipWidth = -1; +const TUint KDefaultClipChar = TUint(0x2026); + +// Constant to use in AknLayoutUtils to indicate that the parameter is not to be used as a override value +const TInt KAknLayoutUtilsDoNotOverride = -1; + +/** +* Text utilities. +* Text truncating and wrapping methods in this class do not support +* text that requires conversion from logical to visual form, +* e.g. Arabic/Hebrew, Thai and Hindi text. Code that needs to support that +* kind of text should use corresponding methods in AknBidiTextUtils instead. +*/ +class AknTextUtils + { +public: + enum TClipDirection + { + EDoNotClip, + EClipFromEnd, + EClipFromBeginning + }; + /** ClipToFit() Generic clipping + + @param aBuffer String that needs to be clipped. will be modified by this call + @param aFont Font used in the code + @param aMaxWidthInPixels Maximum length of text that will not be clipped. + @param aDir Where is the text clipped from. EDoNotClip, EClipFromEnd, EClipFromBeginning. + @param aClipWidth The length of the text after clipping. KDefaultClipWidth will make it use aMaxWidthInPixels. + @param aClipString The representation of three dots. (not really used anywhere - use the default value always or "") + + returns true if the text was clipped and 3 dots were added. + */ + + IMPORT_C static TBool ClipToFit(TDes& aBuffer, + const CFont& aFont, + TInt aMaxWidthInPixels, + TClipDirection aDir=EClipFromEnd, + TInt aClipWidth = KDefaultClipWidth, + const TDesC &aClipString=_L("...")); + + /** ClipToFit() for clipping text inside lists + * + * NOTICE: This method cannot handle situation where the text may dynamically change its size! Especially when you have bitmaps on the right side! + * + * This needs to be done AFTER the listbox has done its SizeChanged()! + */ + IMPORT_C static TBool ClipToFit(TDes& aBuffer, + TClipDirection aDir, + CEikFormattedCellListBox *aListBox, + TInt aItemIndex, + TInt aSubCellNumber); + + /** ClipToFit() for clipping text inside lists + * + * NOTICE: This method cannot handle situation where the text may dynamically change its size! Especially when you have bitmaps on the right side! + * + * This needs to be done AFTER the listbox has done its SizeChanged()! + */ + IMPORT_C static TBool ClipToFit(TDes& aBuffer, + TClipDirection aDir, + CEikColumnListBox *aListBox, + TInt aItemIndex, + TInt aColumnNumber); + + // implementation + + static TBool DoClipToFit( + TDes& aBuffer, + const CFont& aFont, + TInt aMaxWidthInPixels, + TClipDirection aDir, + TInt aClipWidth, + const TDesC& aClipString ); + + /** + * Wraps a string to an array of pointers. + * The number of lines and line widths are specified by aLineWidthArray. + * The pointers in aWrappedArray point to positions inside aWrappedString. + * + * @param aStringToWrap String that needs to be wrapped + * @param aLineWidthArray Line widths in pixels + * @param aFont Used font + * @param aWrappedArray Pointers to wrapped lines + */ + IMPORT_C static void WrapToArrayL( + const TDesC& aStringToWrap, + const CArrayFix& aLineWidthArray, + const CFont& aFont, + CArrayFix& 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& 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& aLineWidthArray, + const CFont& aFont, + CArrayFix& 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& aLineWidthArray, + const CFont& aFont, + CArrayFix& 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& 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& 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& 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& aLineWidthArray, + const CFont& aFont, + TDes& aWrappedString, + TInt aFlags, + TInt aDirectionality ); + + static void WrapToArrayL( + TDes& aStringToWrap, + const CArrayFix* aLineWidthArray, + const CFont& aFont, + CArrayFix& aWrappedArray, + TInt aLineWidth, + TInt aFlags, + TInt aDirectionality ); + + static void ChopToArrayAndClipL( + TDes& aStringToChop, + const CArrayFix* aLineWidthArray, + const CFont& aFont, + CArrayFix& 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 &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 *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 *iShownIndexes; // own // uses non-filtered indexes + CArrayFix *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; } + */ +template +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 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* iGfx; + CArrayReader* iText; + CArrayReader* iCmd; + CArrayReader* 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. + */ + IMPORT_C static void DrawSeparator( CGraphicsContext& aGc, + const TRect& aRect, const TRgb& aColor ); + }; + +#endif // __AKNUTILS_H__ + +// End of file +