1 /*

     2 * Copyright (c) 2004-2005 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

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

     6 * which accompanies this distribution, and is available

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

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  

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

    16 *

    17 */

    18 

    19 

    20    

    21 #ifndef AKNFONTPROVIDER_H

    22 #define AKNFONTPROVIDER_H

    23 

    24 #include <fbs.h>

    25 

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

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

    28 #include <AknFontSpecification.h>

    29 

    30 class TAknFontProviderSuppliedMetrics;

    31 class CEikonEnv;

    32 

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

    34 #define RD_FONT_PROVIDER_EXTENDED_SUPPORT

    35 

    36 // Panic codes for use in Font Provider

    37 enum TAknFontProviderPanicCodes

    38     {

    39     EAknFontPanicIndexOutOfRange,

    40     EAknFontPanicLayoutMissingFontInformation,

    41     EAknFontPanicBadFontProviderDataStructure,

    42     EAknFontPanicFailedToReturnFont,

    43 	EAknFontPanicFontTooBig

    44     };

    45 

    46 const TInt KAknFontProviderBaselineCorrectionIsAbsolute(-1);

    47 

    48 /**

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

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

    51  */

    52 class AknFontProvider

    53     {

    54     public:

    55     /**

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

    57     *

    58     * @since Series 60 release 2.8

    59     * 

    60     * @param aDevice the bitmap device needed for twips calculations

    61     * @param aFontId    Series 60 font id

    62     * @param aMetrics   Series 60 font specification object determining 

    63     *                   layout requirements on the font to be matched.

    64     * @param aAdditionalMetrics Output additional information

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

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

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

    68     */

    69     IMPORT_C static CFbsFont* CreateFontFromMetrics (

    70         CBitmapDevice& aDevice,

    71         TInt aFontId, 

    72         const TAknFontSpecification& aMetrics,

    73         TAknFontProviderSuppliedMetrics& aAdditionalMetrics,

    74         TInt& aFontProviderIndex );

    75 

    76     /**

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

    78     * 

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

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

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

    82     * and then passed to the underlying Symbian OS GetNearestFontInPixels.

    83     * 

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

    85     *

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

    87     * 

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

    89     * 

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

    91     * passed to the underlying Symbian OS font request.

    92     * 

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

    94     * main matching key.

    95     *

    96     * @since Series 60 release 2.8

    97     * 

    98     * @param aTypeface  Symbian OS typeface information.

    99     * @param aMetrics   Series 60 font specification object determining 

   100     *                   layout requirements on the font to be matched.

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

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

   103     *                           row was matched.

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

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

   106     */

   107     IMPORT_C static CFbsFont* CreateFontFromTypefaceAndMetrics (

   108         CBitmapDevice& aDevice,

   109         const TTypeface& aTypeface, 

   110         const TAknFontSpecification& aMetrics,

   111         TAknFontProviderSuppliedMetrics& aAdditionalMetrics,

   112         TInt& aFontProviderIndex );

   113 

   114     /**

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

   116     *

   117     * @since Series 60 release 2.8

   118     * 

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

   120     * @return          EFalse if there is no baseline correction

   121     */

   122     IMPORT_C static TBool HasBaselineCorrection( 

   123         TInt aFontProviderIndex );

   124 

   125     /**

   126     * Provides a character-dependent baseline offset within the font

   127     *

   128     * @since Series 60 release 2.8

   129     * 

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

   131     * @param aCharacter         Character whose baseline correction is queried

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

   133     *                           If aDenominatorIfFractional is not KAknFontProviderBaselineCorrectionIsAbsolute

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

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

   136     */

   137     IMPORT_C static TInt BaselineDeltaForCharacter( 

   138         TInt aFontProviderIndex, 

   139         TChar aCharacter, 

   140         TInt& aBaselineLift, 

   141         TInt& aDenominatorIfFractional );

   142 

   143     /**

   144     * Provides a character-dependent baseline offset within the font

   145     *

   146     * @since Series 60 release 2.8

   147     * 

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

   149     * @param aText              Descriptor whose baseline correction is queried

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

   151     *                           If aDenominatorIfFractional is not KAknFontProviderBaselineCorrectionIsAbsolute, 

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

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

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

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

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

   157     *                               descriptor is recorded in aNumInitialCharsTheSame. 

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

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

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

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

   162     */   

   163     IMPORT_C static TInt MinimumBaselineDeltaForDescriptor( 

   164         TInt aFontProviderIndex, 

   165         const TDesC& aText, 

   166         TInt& aMinBaselineLift, 

   167         TInt& aDenominatorIfFractional,

   168         TBool aQuitWhenDifferent,

   169         TInt& aNumInitialCharsTheSame);

   170 

   171     /**

   172     * Returns a Font provider index from a Symbian Font specification

   173     *

   174     * @since Series 60 release 2.8

   175     * 

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

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

   178     */

   179     IMPORT_C static TInt FontProviderIndexFromFontSpec( const TFontSpec& aFontSpec );

   180 

   181     /**

   182     * Initialize environment for Series 60 font defaults

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

   184     *

   185     * @since Series 60 release 3.0

   186     * @capability WriteDeviceData

   187     * @param aEnv   Eikon environment object reference 

   188     */

   189     IMPORT_C static void InitializeSystemL ( const CEikonEnv& aEnv );

   190 

   191     /**

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

   193     * without actually constructing the font.

   194     *

   195     * @since Series 60 release 5.0

   196     * 

   197     * @param aDevice the bitmap device needed for twips calculations

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

   199     * @param aMetrics   Series 60 font specification object determining 

   200     *                   layout requirements on the font to be matched.

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

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

   203     * @return       KErrNone

   204     */    

   205     IMPORT_C static TInt GetFontSpecFromMetrics(

   206         CBitmapDevice& aDevice,

   207         TInt aFontId, 

   208         const TAknFontSpecification& aMetrics,

   209         TFontSpec& aFontSpec,

   210         TInt& aFontProviderIndex);

   211         

   212 private:

   213     /**

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

   215     * without actually constructing the font. Internal implementation.

   216     *

   217     * @param aDevice the bitmap device needed for twips calculations

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

   219     * @param aMetrics   Series 60 font specification object determining 

   220     *                   layout requirements on the font to be matched.

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

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

   223     * @param aNeedsExactMatch Output whether an exact match was requested

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

   225     * @return       KErrNone

   226     */    

   227     static TInt DoGetFontSpecFromMetrics(

   228         CBitmapDevice& aDevice,

   229         TInt aFontId, 

   230         const TAknFontSpecification& aMetrics,

   231         TFontSpec& aFontSpec,

   232         TInt& aFontProviderIndex,

   233         TBool& aNeedsExactMatch,

   234         TBool& aFallbackNeeded);

   235    };

   236     

   237 #endif