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