--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/uiresources_pub/font_definition_api/inc/AknFontSpecification.h Thu Dec 17 09:14:12 2009 +0200
@@ -0,0 +1,242 @@
+/*
+* 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