uiresources_plat/extended_fonts_api/inc/AknFontProvider.h
changeset 0 05e9090e2422
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/uiresources_plat/extended_fonts_api/inc/AknFontProvider.h	Thu Dec 17 09:14:12 2009 +0200
@@ -0,0 +1,237 @@
+/*
+* 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