/*

* Copyright (c) 2004-2005 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:  

*   Interface for controlling the font choices made via Series 60 according to installed fonts

*

*/

#ifndef AKNFONTPROVIDER_H

#define AKNFONTPROVIDER_H

#include <fbs.h>

// When this header is included from FontProvider component (licensee-customizable), the following

// will not be in the User Include path, but in the System Include:

#include <AknFontSpecification.h>

class TAknFontProviderSuppliedMetrics;

class CEikonEnv;

// note that this flag must be removed by 2008wk02, for temporary internal compatibility use only

#define RD_FONT_PROVIDER_EXTENDED_SUPPORT

// Panic codes for use in Font Provider

enum TAknFontProviderPanicCodes

    {

    EAknFontPanicIndexOutOfRange,

    EAknFontPanicLayoutMissingFontInformation,

    EAknFontPanicBadFontProviderDataStructure,

    EAknFontPanicFailedToReturnFont,

	EAknFontPanicFontTooBig

    };

const TInt KAknFontProviderBaselineCorrectionIsAbsolute(-1);

/**

 * Class to provide runtime matching of font specification to available fonts.

 * The class is customizable by licensees by re-implementing this CPP file.

 */

class AknFontProvider

    {

    public:

    /**

    * Returns a font that matches the metrics supplied (aMetrics) from a product specific list. 

    *

    * @since Series 60 release 2.8

    * 

    * @param aDevice the bitmap device needed for twips calculations

    * @param aFontId    Series 60 font id

    * @param aMetrics   Series 60 font specification object determining 

    *                   layout requirements on the font to be matched.

    * @param aAdditionalMetrics Output additional information

    * @param aFontProviderIndex Output index for using in subsequent calls into other APIs

    * @return           a font pointer.  No ownership is transferred. 

    *                   Clients must call CBitmapDevice->ReleaseFont() when the font is no longer required.

    */

    IMPORT_C static CFbsFont* CreateFontFromMetrics (

        CBitmapDevice& aDevice,

        TInt aFontId, 

        const TAknFontSpecification& aMetrics,

        TAknFontProviderSuppliedMetrics& aAdditionalMetrics,

        TInt& aFontProviderIndex );

    /**

    * Returns a font that matches the typeface information and metrics supplied.

    * 

    * The typeface name supplied is checked against the supported alias table.

    * Generic alias names ("SansSerif", "Serif", "Monospace") are mapped to the product's fonts

    * taking supported languages, size, styles into account (ie, matched against the product font table), 

    * and then passed to the underlying Symbian OS GetNearestFontInPixels.

    * 

    * Other aliased typeface names may be mapped to font groups within the product font table

    *

    * Some aliased typeface names may be mapped to a single typeface, and matched against the product font table.

    * 

    * If no aliasing occurs, the passed-in typeface name is matched against the product font table.

    * 

    * If no match is found in the product font table, then the typeface (possibly after alias mapping) is

    * passed to the underlying Symbian OS font request.

    * 

    * The Category member of TAknFontSpecification is ignored when using this API; the typeface info is the 

    * main matching key.

    *

    * @since Series 60 release 2.8

    * 

    * @param aTypeface  Symbian OS typeface information.

    * @param aMetrics   Series 60 font specification object determining 

    *                   layout requirements on the font to be matched.

    * @param aFontProviderIndex Output index for using in subsequent calls into other APIs

    *                           This will be returned as KErrNotFound if no matching product font table

    *                           row was matched.

    * @return           a font pointer.  No ownership is transferred. 

    *                   Clients must call CBitmapDevice->ReleaseFont() when the font is no longer required.

    */

    IMPORT_C static CFbsFont* CreateFontFromTypefaceAndMetrics (

        CBitmapDevice& aDevice,

        const TTypeface& aTypeface, 

        const TAknFontSpecification& aMetrics,

        TAknFontProviderSuppliedMetrics& aAdditionalMetrics,

        TInt& aFontProviderIndex );

    /**

    * Tells the caller if the font obtained at a given index has corrected baselines

    *

    * @since Series 60 release 2.8

    * 

    * @param aFontProviderIndex Input index obtained in the call to CreateFontFromMetrics

    * @return          EFalse if there is no baseline correction

    */

    IMPORT_C static TBool HasBaselineCorrection( 

        TInt aFontProviderIndex );

    /**

    * Provides a character-dependent baseline offset within the font

    *

    * @since Series 60 release 2.8

    * 

    * @param aFontProviderIndex Input index obtained in the call to CreateFontFromMetrics

    * @param aCharacter         Character whose baseline correction is queried

    * @param aBaselineLift      Output; Baseline lift. +ve if baseline is raised. 

    *                           If aDenominatorIfFractional is not KAknFontProviderBaselineCorrectionIsAbsolute

    *                           then aBaselineLift needs to be divided by it, and multiplied by the font height

    * @param aDenominatorIfFractional Output; if non-zero, then the baseline lift is proportional

    */

    IMPORT_C static TInt BaselineDeltaForCharacter( 

        TInt aFontProviderIndex, 

        TChar aCharacter, 

        TInt& aBaselineLift, 

        TInt& aDenominatorIfFractional );

    /**

    * Provides a character-dependent baseline offset within the font

    *

    * @since Series 60 release 2.8

    * 

    * @param aFontProviderIndex Input index obtained in the call to CreateFontFromMetrics

    * @param aText              Descriptor whose baseline correction is queried

    * @param aMinBaselineLift   Output; Baseline lift. +ve if baseline is raised. 

    *                           If aDenominatorIfFractional is not KAknFontProviderBaselineCorrectionIsAbsolute, 

    *                           then aBaselineLift needs to be divided by it, and multiplied by the font height

    * @param aDenominatorIfFractional Output; if value is not KAknFontProviderBaselineCorrectionIsAbsolute, 

    *                           then the baseline lift is proportional to height, but need dividing by this value.

    * @param aQuitWhenDifferent     Input; if ETrue, stop scanning the descriptor when a different 

    *                               baseline lift is seen. Number of characters in the uniform, leading part of the

    *                               descriptor is recorded in aNumInitialCharsTheSame. 

    *                               If EFalse, the entire descriptor is looked at, and the minimum baseline lift 

    *                               returned. aNumInitialCharsTheSame is still just the leading uniform sequence (same as if ETrue)

    * @param aNumInitialCharsTheSame    Counts the number of characters in the leading sequence of uniformly baselined chars

    * @return   KErrNotFound if the input aFontProviderIndex is invalid. Otherwise KErrNone.

    */   

    IMPORT_C static TInt MinimumBaselineDeltaForDescriptor( 

        TInt aFontProviderIndex, 

        const TDesC& aText, 

        TInt& aMinBaselineLift, 

        TInt& aDenominatorIfFractional,

        TBool aQuitWhenDifferent,

        TInt& aNumInitialCharsTheSame);

    /**

    * Returns a Font provider index from a Symbian Font specification

    *

    * @since Series 60 release 2.8

    * 

    * @param aFontSpec  Symbian OS font specification.  Typeface name needs to be filled in.

    * @return Index into the font provider (for use calling back to other routines), or KErrNotFound, if no match is made

    */

    IMPORT_C static TInt FontProviderIndexFromFontSpec( const TFontSpec& aFontSpec );

    /**

    * Initialize environment for Series 60 font defaults

    * This method is to be called internally by the UI system early during initialization.

    *

    * @since Series 60 release 3.0

    * @capability WriteDeviceData

    * @param aEnv   Eikon environment object reference 

    */

    IMPORT_C static void InitializeSystemL ( const CEikonEnv& aEnv );

    /**

    * Returns a font spec that matches the metrics supplied (aMetrics) from a product specific list,

    * without actually constructing the font.

    *

    * @since Series 60 release 5.0

    * 

    * @param aDevice the bitmap device needed for twips calculations

    * @param aFontId    Series 60 font id, not currently used

    * @param aMetrics   Series 60 font specification object determining 

    *                   layout requirements on the font to be matched.

    * @param aFontSpec Output font spec corresponding to the requested font

    * @param aFontProviderIndex Output index for using in subsequent calls into other APIs

    * @return       KErrNone

    */    

    IMPORT_C static TInt GetFontSpecFromMetrics(

        CBitmapDevice& aDevice,

        TInt aFontId, 

        const TAknFontSpecification& aMetrics,

        TFontSpec& aFontSpec,

        TInt& aFontProviderIndex);

private:

    /**

    * Returns a font spec that matches the metrics supplied (aMetrics) from a product specific list,

    * without actually constructing the font. Internal implementation.

    *

    * @param aDevice the bitmap device needed for twips calculations

    * @param aFontId    Series 60 font id, not currently used

    * @param aMetrics   Series 60 font specification object determining 

    *                   layout requirements on the font to be matched.

    * @param aFontSpec Output font spec corresponding to the requested font

    * @param aFontProviderIndex Output index for using in subsequent calls into other APIs

    * @param aNeedsExactMatch Output whether an exact match was requested

    * @param aFallbackNeeded Output ETrue iff a fallback was needed in order to match

    * @return       KErrNone

    */    

    static TInt DoGetFontSpecFromMetrics(

        CBitmapDevice& aDevice,

        TInt aFontId, 

        const TAknFontSpecification& aMetrics,

        TFontSpec& aFontSpec,

        TInt& aFontProviderIndex,

        TBool& aNeedsExactMatch,

        TBool& aFallbackNeeded);

   };

#endif