/*

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

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

* which accompanies this distribution, and is available

* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description: 

*  Access to Series 60 font system

* 

*

*/

#ifndef __AKNFONTACCESS_H__

#define __AKNFONTACCESS_H__

class CAknLayoutFont;

class CFbsFont;

#include <AknFontSpecification.h>

class AknFontAccess

    {

public:

    /**

    * Generic font family enumeration. These can be used in place of the family name descriptors

    */

    enum TAknFontFamily

        {

        EAknFontFamilyNotSpecified = 0,

        EAknFontFamilySansSerif,

        EAknFontFamilySerif,

        EAknFontFamilyMonospace

        };

public:

    /**

    * Returns a font that matches the metrics supplied. The provider can return a scaled 

    * or bitmap font as long as it meets the provided criteria. If an exact match isn't 

    * found then a null is returned.

    *

    * @since Series 60 release 2.8

    * 

    * @param aBitmapDevice Device for which the font will be requested 

    * @param aFontStyle of type TFontStyle. Use to set weight and posture of the font

    * @param aFontSize  Font size in twips. 

    * @param aFontFamily Font is one of the enumerations in TAknFontFamily

    *        Note that serif and sansSerif are proportional fonts 

    * 

    * @return A font pointer. CBitmapDevice::ReleaseFont must be called to release the font resource on the

    * device context when the font is no longer required. If an exact match isn't found NULL is returned

    */

    IMPORT_C static CFbsFont* GetFont(

        CBitmapDevice& aBitmapDevice,        

        const TFontStyle aFontStyle,

        TInt aFontSizeInTwips, 

        TAknFontFamily aFontFamily); 

    /**

    * Returns a font that matches the metrics supplied. The provider can return a scaled 

    * or bitmap font as long as it meets the provided criteria. If an exact match isn't 

    * found than a null is returned.

    *

    * @since Series 60 release 2.8

    * 

    * @param aBitmapDevice Device for which the font will be requested 

    * @param aFontStyle of type TFontStyle. Use to set weight and posture of the font

    * @param aFontSize Font size in twips. 

    * @param aFontFamilyname Font family is the text name of the font family and may be, for example:

    *               "courier", "helvetica", "times roman" etc. Font names are not case-sensitive. 

    * 

    * @return A font pointer. CBitmapDevice::ReleaseFont must be called to release the font resource on the

    * device context when the font is no longer required. If an exact match isn't found NULL is returned

    */

    IMPORT_C static CFbsFont* GetFont(

        CBitmapDevice& aBitmapDevice,        

        const TFontStyle aFontStyle, 

        TInt aFontSizeInTwips, 

        const TDesC& aFontFamilyName); 

    /**

    * Returns a font that matches the metrics supplied. The provider can return a scaled 

    * or bitmap font as long as it meets the provided criteria. A best fit is used that 

    * is prioritized as follows: fontSize, fontStyle, fontFamily 

    * This will succeed as long as there is at least one font on the phone. 

    * @since Series 60 release 2.8

    * 

    * @param aBitmapDevice Device for which the font will be requested 

    * @param aFontStyle of type TFontStyle. Use to set weight and posture of the font

    * @param aFontSize Font size in twips. 

    * @param aFontFamily Font is one of the following emumerations values: 

    *         monospace, sansSerif, serif 

    *        Note that serif and sansSerif are proportional fonts 

    * 

    * @return A font pointer. CBitmapDevice::ReleaseFont must be called to release the font resource on the

    * device context when the font is no longer required.  A font is always returned.

    */

    IMPORT_C static CFbsFont* GetClosestFont(

        CBitmapDevice& aBitmapDevice,        

        const TFontStyle aFontStyle, 

        TInt aFontSizeInTwips, 

        TAknFontFamily aFontFamily); 

    /**

    * Returns a font that matches the metrics supplied. The provider can return a scaled 

    * or bitmap font as long as it meets the provided criteria. A best fit is used that 

    * is prioritized as follows: fontSize, fontStyle, fontFamily 

    * This will succeed as long as there is at least one font on the phone.

    * @since Series 60 release 2.8

    * 

    * @param aBitmapDevice Device for which the font will be requested 

    * @param aFontStyle of type TFontStyle. Use to set weight and posture of the font

    * @param aFontSize Font size in twips. 

    * @param aFontFamilyname Font family is the text name of the font family and may be, for example:

    *               "courier", "helvetica", "times roman" etc. Font names are not case-sensitive. 

    * 

    * @return A font pointer. CBitmapDevice::ReleaseFont must be called to release the font resource on the

    * device context when the font is no longer required.  A font is always returned.

    */

    IMPORT_C static CFbsFont* GetClosestFont(

        CBitmapDevice& aBitmapDevice,        

        const TFontStyle aFontStyle, 

        TInt aFontSizeInTwips, 

        const TDesC& aFontFamilyName); 

    /**

    * 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.

    * 

    * This method can only be used for TAknFontSpecification objects that are stored in Pixels. 

    * (See TAknFontSpecification::Units() )

    *

    * @since Series 60 release 2.8

    * @param aBitmapDevice  Device for which the font is required (not used in 2.8; CEikonEnv::ScreenDevice() is used)

    * @param aSpec          Series 60 font specification object

    * @return               pointer to a CAknLayoutFont object, owned by the caller

    */

    IMPORT_C static CAknLayoutFont* CreateLayoutFontFromSpecificationL(

        CBitmapDevice& aBitmapDevice,   

        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 Series 60  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.

    * 

    * This method can only be used for TAknFontSpecification objects that are stored in Pixels

    * (See TAknFontSpecification::Units() )

    *

    * @since Series 60 release 2.8

    * @param aBitmapDevice  Device for which the font is required (not used in 2.8; CEikonEnv::ScreenDevice() is used)

    * @param aTypeface      Symbian Typface object

    * @param aSpec             Series 60 font specification object

    * @return                       pointer to a CAknLayoutFont object, owned by the caller

    */

    IMPORT_C static CAknLayoutFont* CreateLayoutFontFromSpecificationL(

        CBitmapDevice& aBitmapDevice,        

        const TTypeface& aTypeface, 

        const TAknFontSpecification& aSpec);

private:

    /**

    * Method containing all the real implementation for the GetFontXXX APIs

    */

    static CFbsFont* DoGetFont( 

        CBitmapDevice& aBitmapDevice,        

        const TFontStyle aFontStyle, 

        TInt aFontSizeInTwips, 

        const TTypeface& aFontFamilyTypeface,

        TBool aExactMatchRequired);                 

    };

#endif //  __AKNFONTACCESS_H__

// End of file