/*

* Copyright (c) 2002-2008 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: 

*

*/

#ifndef AKNFONTSPECIFICATION_H

#define AKNFONTSPECIFICATION_H

#include <gdi.h>

#include <AknFontCategory.hrh>

#include <babitflags.h>

/**

* Object representing the series 60 requirements for a font. It contains information

* from the layout specification that fonts bound to the given font id should honor.

* 

* It formst the basis of the request to font provisioning to provide a suitable font

*

*  @lib FontUtils.lib

*  @since 2.8

*

*  @internal

*/

class TAknFontSpecification

    {

public:

    enum TAknFontSpecificationUnits

        {

        EPixels = 0,

        ETwips

        };

public:

    /**

    * Construct font specification from Font ID.

    *

    *@param aFontId     Series 60 font id from which to create a font.

    */

    IMPORT_C TAknFontSpecification( TInt aFontId );

    /**

    * Construct the font specifiation from Symbian OS TFontSpec and MGraphicsDeviceMap

    * The Symbian OS TFontSpec must be set in Twips.  The MGraphicsDeviceMap is used to convert to

    * pixels for the text pane height.

    *

    * Note that the units policy during and in effect at the end of this constructor is EPixels.

    * 

    * Note that the TTypeface part of the TFontSpec is lost in this construction

    *

    * @param aCategory      Series 60 Font category to use

    * @param aFontSpec      Provides the metrics and Style information to use for the match

    * @param aDeviceMap     Device map used to convert the aFontSpec's twips to pixels

    * 

    */

    IMPORT_C TAknFontSpecification(  

        TAknFontCategory aCategory, 

        const TFontSpec& aFontSpec, 

        const MGraphicsDeviceMap* aDeviceMap );

    /**

    * Sets the Series 60 font category.

    * 

    * @param aCategory  New category to set.

    */

    IMPORT_C void SetFontCategory( TAknFontCategory aCategory );

    /**

    * Series 60 Layout Specification font category: 

    *   Primary, Secondary, Title etc.

    *

    * @return   Series 60 font category

    */

    IMPORT_C TAknFontCategory FontCategory() const;

    /**

    * The requested height for a font. This represents the maximum vertical range that can be 

    * guraranteed to draw in the text pane.

    *

    * Note also that this value is the height requested by layout or the client, and might not correspond to 

    * the design height, ascent + descent, or max height reported by the attached font. See the APIs

    * CAknLayoutFont::TextPaneTopToBaseline and BaselineToTextPaneBottom. 

    *

    * If TextPaneHeightIsDesignHeight() is EFalse, then the font will be requested to fit entirely within

    * this range.  

    *

    * If TextPaneHeightIsDesignHeight() is set, then this value is passed to the font request as the font

    * design height, in which case the font may not render entirely within the "text pane height".

    * 

    * @param aNewHeight     Text pane height to be used by the font.

    */

    IMPORT_C void SetTextPaneHeight( TInt aNewHeight );

    /**

    * The requested height of the font. This represents the maximum vertical range that can be 

    * guaranteed to draw in the text pane.

    *

    * Note also that this value is the height requested by layout or the client, and may not correspond to 

    * the design height, ascent + descent, or max height reported by the attached font. See the APIs

    * CAknLayoutFont::TextPaneTopToBaseline and BaselineToTextPaneBottom. 

    * 

    * If TextPaneHeightIsDesignHeight() is EFalse, then the font is to be requested to fit entirely within

    * this range.  

    *

    * If TextPaneHeightIsDesignHeight() is set, then this value is passed to the font request as the font

    * design height, in which case the font may not render entirely within the "text pane height".

    *

    * Depending upon the value of TextPaneHeightIsInTwips(), the value returned is in Pixels or Twips. 

    * Note that calling SetTextPaneHeightIsInTwips() does not perform any conversion of the text pane height;

    * It retains its set value.

    * 

    * @return Requested text pane height.

    */

    IMPORT_C TInt TextPaneHeight() const;

    /**

    * Set the stoke weight to request using the Symbian OS stroke weight enumeration. 

    *

    * @aParam aWeight   The stroke weight. 

    */

    IMPORT_C void SetWeight( TFontStrokeWeight aWeight );

    /**

    * Sets the posture (e.g. upright, italic) of requested font using the Symbian OS enumeration.

    * @param aPostore   posture to request

    */

    IMPORT_C void SetPosture( TFontPosture aPosture );

    /**

    * Sets the policy to use in requesting the font height. Fonts may be requested either by "design height" (which is 

    * usually approximately the ascent + descent) or by maximum height.

    * If false, this setting means the number set by SetTextPaneHeight is intended to match

    * the font's maximum extent; all characters will fit within the text pane.

    * If true, then the value passed by SetTextPaneHeight will be used to request design height.

    *

    * This API has no effect if called on a TAknFontSpecification that has already been bound to a font

    *

    * The default value upon construction is EFalse.

    *

    * @param aTextPaneHeightIsDesignHeight  If EFalse, ensure that the font fits entirely

    *                                       within the text pane height

    *                                       If not EFalse, then the text pane height is treated as the font

    *                                       design height.

    */

    IMPORT_C void SetTextPaneHeightIsDesignHeight( TBool aTextPaneHeightIsDesignHeight );

    /**

    * Accessor API for the height policy.

    * 

    * @return   EFalse if text pane height is to be the maximum font extent.

    *           ETrue if text pane height is to be treated as the font's design height 

    */

    IMPORT_C TBool TextPaneIsDesignHeight() const;

    /**

    * Sets a flag indicating to font requests whether they should insist upon an exact match.

    * Whether a font match is treated as exact or not depends upon various things, including:

    *     - if a request is made via a generic font family or via a font family enumeration, then typeface is not tested for "exactness"

    *     - fonts may be forced to be rendered at certain sizes (within a small number of pixels). This still counts as an exact match

    * 

    * The default value upon construction is EFalse;

    *

    * @param aRequiresExactMatch       

    */

    IMPORT_C void SetExactMatchRequired ( TBool aRequiresExactMatch );

    /**

    * Accessor API for whether an exact match is required for the font (See SetExactMatchRequired() )

    *

    * @return   whether an exact match is required or not.

    */

    IMPORT_C TBool ExactMatchRequired() const;

    /**

    * Sets the units for the Text Pane Height APIs.  Note that calling this API does not 

    * result in the numerical value of the text pane height being recalculated. 

    * Upon construction, TAknFontSpecification objects store TextPaneHeight in pixels. 

    * If you then call SetUnits to Twips, you will also have to call SetTextPaneHeight to pass in the new

    * (twips) value. 

    *

    * @param aUnits

    */

    IMPORT_C void SetUnits( TAknFontSpecification::TAknFontSpecificationUnits aUnits );

    /**

    * Accessor API for the units being used.

    *

    * @return units currently being used.

    */

    IMPORT_C TAknFontSpecification::TAknFontSpecificationUnits Units() const;     

    /**

    * Accessor for the requested weight

    *

    * @return Symbian OS stroke weight enumeration (e.g. EStrokeWeightBold)

    */

    IMPORT_C TFontStrokeWeight Weight() const ;

    /**

    * Accessor for the requested posture

    *

    * @return Symbian OS font posture enumeration (e.g. EPostureItalic)

    */

    IMPORT_C TFontPosture Posture() const;

    /**

    * Accessor for the requested outline effect 

    *

    * @since 5.0

    *

    * @return ETrue iff outline font effect has been requested

    */

    IMPORT_C TBool IsOutlineEffectOn() const;

private:

    void LoadAnyCDLFontInstanceL();

private:

    TAknFontCategory iBaseFontCategory;

    TInt iTextPaneHeight;

    // Symbian OS Font Style object convenient for holding style info

    TFontStyle iRequiredStyle;

    TBitFlags iFlags;

    TInt iSpare2; 

    };

#endif

// End of File