1 // Copyright (c) 2010 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

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

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 // This file is a subset of original gdi.h.

    15 //

    16 // IMPORTANT NOTE to maintainer:

    17 //     If you add new exports, to make sure they are exported by GDI.DLL,

    18 //     remember to update /graphics/graphicsdeviceinterface/gdi/sgdi/TextBaseStub.cpp.

    19 //

    20 // Text related types/consts are moved from gdi.h to this file, as listed below.

    21 //

    22 // enum TFontPosture

    23 // enum TFontStrokeWeight

    24 // enum TFontPrintPosition

    25 //

    26 // const KMaxTypefaceNameLength

    27 // class TTypeface

    28 // enum TGlyphBitmapType

    29 // class FontEffect

    30 // class TFontStyle

    31 // class TFontSpec

    32 // class TTypefaceSupport

    33 // const KSuperSubScalingPercentage

    34 // const KSuperscriptOffsetPercentage

    35 // const KSubscriptOffsetPercentage

    36 // class CTypefaceStore

    37 // const KMaxFontCacheEntries

    38 // class CFontCache

    39 //

    40 // const KFontCapitalAscent

    41 // const KFontMaxAscent

    42 // const KFontStandardDescent

    43 // const KFontMaxDescent

    44 // const KFontLineGap

    45 // const KFontGetFontTable

    46 // const KFontGetGlyphOutline

    47 // const KFontReleaseGlyphOutline

    48 // const KFontReleaseFontTable

    49 // class CFont

    50 

    51 

    52 #ifndef __TEXTBASE_H__

    53 #define __TEXTBASE_H__

    54 

    55 #include <e32base.h>

    56 #include <f32file.h>

    57 #include <s32std.h>

    58 

    59 class TOpenFontCharMetrics;

    60 class RShapeInfo;

    61 

    62 

    63 #ifndef __GLYPHSEL_TEXTBASE_H__

    64 #define __GLYPHSEL_TEXTBASE_H__

    65 /**

    66 This enumeration holds the possible panic codes that may be raised 

    67 by the TextBase API on detecting an unrecoverable error. */

    68 enum TTextBasePanic

    69 	{

    70 	/** Not used */

    71 	ETextBasePanic_Unknown				= 0,

    72 	/** One or more of the input parameters to the interface were invalid */

    73 	ETextBasePanic_InvalidInputParam		= 1,

    74 	/** Insufficient text for successful completion of the method */

    75 	ETextBasePanic_OutOfText				= 2,

    76 	/** Internal failure. */

    77 	ETextBasePanic_Invariant				= 3,

    78 	/** Reserved panic codes. Not to be used. */

    79 	ETextBasePanic_Reserved1				= 4,

    80 	ETextBasePanic_Reserved2				= 5,

    81 	/** Setting a typeface name that is too long */

    82 	ETextBasePanic_TypefaceNameOverflow	= 6,

    83 	};

    84 #endif

    85 

    86 

    87 /**

    88 Font posture flags.

    89 Fonts can be either upright or italic. 

    90 @publishedAll	

    91 @released

    92 */

    93 enum TFontPosture

    94 	{

    95 	/** Font posture is normal (upright). */

    96 	EPostureUpright,

    97 	/** Font posture is italic. */

    98 	EPostureItalic

    99 	};

   100 

   101 

   102 /**

   103 Font stroke weight flags. 

   104 @publishedAll	

   105 @released

   106 */

   107 enum TFontStrokeWeight

   108 	{

   109 	/** Font stroke weight is normal. */

   110 	EStrokeWeightNormal,

   111 	/** Font stroke weight is bold. */

   112 	EStrokeWeightBold

   113 	};

   114 

   115 /**

   116 Font print position flags.

   117 Fonts can be normal, superscript or subscript. 

   118 @publishedAll	

   119 @released

   120 */

   121 enum TFontPrintPosition

   122 	{

   123 	/** Font is normal. */

   124 	EPrintPosNormal,

   125 	/** Font is superscript. */

   126 	EPrintPosSuperscript,

   127 	/** Font is subscript. */

   128 	EPrintPosSubscript

   129 	};

   130 

   131 

   132 /**

   133 The maximum length of a typeface name (in characters). 

   134 @publishedAll	

   135 @released

   136 */

   137 const TInt KMaxTypefaceNameLength=0x18;

   138 

   139 

   140 /** Typeface name and attributes.

   141 

   142 This class identifies a typeface by name, and contains the combination of 

   143 attributes of the typeface. These attributes define whether it is a symbol 

   144 typeface, whether the typeface is proportional, and whether it is serif or 

   145 sans-serif. 

   146 

   147 The combination of attributes for a typeface are stored in a bitmask, with 

   148 the various bits indicating different attributes. The bitmask is calculated 

   149 for any particular attribute combination by ORing the enumerated value for 

   150 each individual attribute. 

   151 @publishedAll 

   152 @released

   153 */

   154 class TTypeface

   155     {

   156 public:

   157 	enum

   158 		{

   159 		/** Typeface is a proportional typeface (e.g. Swiss)

   160 		*/

   161 		EProportional = 1,

   162 		/** Typeface is a serif typeface (e.g. Times)

   163 		*/

   164 		ESerif = 2,

   165 		/** Typeface is a symbol typeface (e.g. Symbol)

   166 		*/

   167 		ESymbol = 4,

   168 		};

   169 public:

   170 	IMPORT_C TTypeface();

   171 	IMPORT_C TBool operator==(const TTypeface& aTypeface) const;

   172 	IMPORT_C void InternalizeL(RReadStream& aStream);

   173 	IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

   174 	IMPORT_C void SetAttributes(TInt aAttributes);

   175 	IMPORT_C void SetIsProportional(TBool aIsProportional);

   176 	IMPORT_C void SetIsSerif(TBool aIsSerif);

   177 	IMPORT_C void SetIsSymbol(TBool aIsSymbol);

   178 	IMPORT_C TInt Attributes() const;

   179 	IMPORT_C TBool IsProportional() const;

   180 	IMPORT_C TBool IsSerif() const;

   181 	IMPORT_C TBool IsSymbol() const;

   182 	IMPORT_C void SetScriptTypeForMetrics(TLanguage aLanguage);

   183 	IMPORT_C void SetScriptTypeForMetrics(TInt aScript);

   184 	IMPORT_C TInt ScriptTypeForMetrics() const;

   185 	IMPORT_C void SetName(const TDesC& aName);

   186 	IMPORT_C const TDesC& Name() const;

   187 private:

   188 	void ResetAttributes();

   189 	void ResetScriptType();

   190 public:

   191 	/** The typeface name. */

   192     TBufC<KMaxTypefaceNameLength> iName;

   193 private:

   194     TUint32 iFlags;

   195     };

   196 

   197 

   198 /**

   199 An enumerated type for the format of a glyph bitmap. This type is currently 

   200 used to indicate whether glyph bitmaps for scalable fonts are drawn anti-aliased. 

   201 Additional values may be defined in the future.

   202 

   203 @see TFontStyle::SetBitmapType()

   204 @see CFbsTypefaceStore::SetDefaultBitmapType() 

   205 @publishedAll

   206 @released	

   207 */

   208 enum TGlyphBitmapType

   209 	{

   210 	/** The font store's default glyph bitmap format is used. */

   211 	EDefaultGlyphBitmap = 0,

   212 	/** The standard monochrome format: no anti-aliasing, 1 bit per pixel, 

   213 	run-length encoded. */

   214 	EMonochromeGlyphBitmap,

   215 	/** Standard 8-bits-per-pixel with anti-aliasing. */

   216 	EAntiAliasedGlyphBitmap,

   217 	/** The format used when sub-pixel font rendering is used. */

   218 	ESubPixelGlyphBitmap,

   219 	/** The format used when outline and shadow font rendering is used. 

   220 

   221 	If the raterizer supports the outline and shadow fonts, it will set the bitmaptype as 

   222 	EFourColourBlendGlyphBitmap but only when glyph bitmap type is set as EAntiAliasedGlyphBitmap and 

   223 	when any of the EDropShadow or EOutline effect is on. Only rasterizer providers can use this enum.

   224 	*/

   225 	EFourColourBlendGlyphBitmap,

   226 	/**

   227 	This is used for glyphs, and not fonts, and is needed to inform the font drawing routines

   228 	that the character should be drawn using the overall font setting. 

   229 	For Internal Use Only.

   230 	*/

   231 	EGlyphBitmapTypeNotDefined,

   232 	/**

   233 	This is used to inform the rasterizer that the best match should be

   234 	found for the bitmap type based upon its knowledge.

   235 	For Internal Use Only.

   236 	*/

   237 	EAntiAliasedOrMonochromeGlyphBitmap,

   238 	};

   239 

   240 /**

   241 Defines a set of font effects flags.

   242 

   243 @publishedAll 

   244 @released

   245 WARNING: This Class is for use by system/UI software ONLY.

   246 */

   247 NONSHARABLE_CLASS(FontEffect)

   248 	{

   249 public:

   250 	enum TEffect

   251 		{

   252 		ENone			= 0x0,		// No effects.

   253 		EAlgorithmicBold= 0x10,		// Font is algorithmic bold (a.k.a pseudo bold.)

   254 		EDropShadow		= 0x20,		// Font has a drop shadow.

   255 		EOutline		= 0x40,		// Font is an outline font.

   256 		EEmbossed		= 0x80,		// Font is embossed.

   257 		EEngraved		= 0x100,	// Font is engraved.

   258 		ESoftEdge		= 0x200,	// Font is soft edged.

   259 		EReserved1		= 0x400,	// Reserved for Symbian use.

   260 		EReserved2		= 0x800,	// Reserved for Symbian use.

   261 		EReserved3		= 0x1000,	// Reserved for Symbian use.

   262 		EReserved4		= 0x2000,	// Reserved for Symbian use.

   263 		EReserved5		= 0x4000,	// Reserved for Symbian use.

   264 		EReserved6		= 0x8000,	// Reserved for Symbian use.

   265 		};

   266 public:

   267 	IMPORT_C static TBool IsEffectOn(TEffect aEffect, TUint32 aFontEffect);

   268 	IMPORT_C static void SetEffect(TEffect aEffect, TBool aOn, TUint32& aFontEffect);

   269 	};

   270 

   271 /** Encapsulates a font style. 

   272 

   273 The font style information is comprised of:

   274 

   275 the posture of the font upright or italic

   276 

   277 the stroke weight of the font  normal or bold

   278 

   279 the print position of the font normal, subscript or superscript

   280 

   281 Note that the underline and strike-through attributes are not included in 

   282 this class, but are set in the graphics context.

   283 

   284 @see CGraphicsContext::SetUnderlineStyle()

   285 @see CGraphicsContext::SetStrikethroughStyle() 

   286 @publishedAll

   287 @released

   288 */

   289 class TFontStyle

   290 	{

   291 public:

   292 	IMPORT_C TFontStyle();

   293 	IMPORT_C TFontStyle(TFontPosture aPost,TFontStrokeWeight aStrWgt,TFontPrintPosition aPrintPos);

   294 	IMPORT_C void InternalizeL(RReadStream& aStream);

   295 	IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

   296 	IMPORT_C TFontPosture Posture() const;

   297 	IMPORT_C TFontStrokeWeight StrokeWeight() const;

   298 	IMPORT_C TFontPrintPosition PrintPosition() const;

   299 	IMPORT_C void SetPosture(TFontPosture aPosture);

   300 	IMPORT_C void SetStrokeWeight(TFontStrokeWeight aStrokeWeight);

   301 	IMPORT_C void SetPrintPosition(TFontPrintPosition aPrintPosition);

   302 	inline TGlyphBitmapType BitmapType() const;

   303 	inline void SetBitmapType(TGlyphBitmapType aBitmapType);

   304 	IMPORT_C TBool operator==(const TFontStyle& aFontStyle) const;

   305 	IMPORT_C TUint32 Effects() const;

   306 	IMPORT_C TBool IsEffectOn(FontEffect::TEffect aEffect) const;

   307 	IMPORT_C void SetEffects(TUint32 aEffects);

   308 	IMPORT_C void SetEffects(FontEffect::TEffect aEffect, TBool aOn);

   309 private:

   310 	enum

   311 		{

   312 		EItalic=0x1,

   313 		EBold=0x2,

   314 		ESuper=0x4,

   315 		ESub=0x8

   316 		};

   317 private:

   318 	TUint32 iFlags; // bitmap type - 16 bits (high), font effects - 12 bits (middle), style - 4 bits (low)

   319 	TAny* iReserved1;

   320 	TAny* iReserved2;

   321 	};

   322 

   323 

   324 

   325 /**

   326 Specifies the font specification in device independent terms.

   327 @publishedAll 

   328 @released

   329 */

   330 class TFontSpec

   331 	{

   332 public:

   333 	IMPORT_C TFontSpec();

   334 	IMPORT_C TFontSpec(const TDesC& aTypefaceName,TInt aHeight);

   335 	IMPORT_C TBool operator==(const TFontSpec& aFontSpec) const;

   336 	IMPORT_C void InternalizeL(RReadStream& aStream);

   337 	IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

   338 	IMPORT_C void SetScriptTypeForMetrics(TLanguage aLanguage);

   339 	IMPORT_C TInt ScriptTypeForMetrics() const;

   340 public:

   341 	/** The typeface. */

   342 	TTypeface iTypeface;

   343 	/** The height of the typeface (in twips). */

   344 	TInt iHeight;

   345 	/** The font style of the typeface. */

   346 	TFontStyle iFontStyle;

   347 	};

   348 

   349 

   350 

   351 /** Typeface family support information.

   352 

   353 This data-only class includes the name and attributes of a typeface, how many 

   354 font heights are available, its minimum and maximum heights, and whether or 

   355 not it is scaleable  a typeface is scaleable if it supports heights at 

   356 fixed intervals between the minimum and maximum heights. 

   357 @publishedAll 

   358 @released

   359 */

   360 class TTypefaceSupport

   361     {

   362 public:

   363 	/** The name and attributes of the typeface. */

   364     TTypeface iTypeface;

   365 	/** The number of distinct font heights available in the typeface. */

   366     TInt iNumHeights;

   367 	/** The typeface's minimum font height, in twips. */

   368     TInt iMinHeightInTwips;

   369 	/** The typeface's maximum font height, in twips. */

   370     TInt iMaxHeightInTwips;

   371 	/** Whether the typeface is scaleable. ETrue if it is scaleable, otherwise 

   372 	EFalse. */

   373     TBool iIsScalable; // supports heights from min to max at fixed interval

   374     };

   375 

   376 /**

   377 The percentage used to multiply a normal font height when calculating its 

   378 superscript or subscript height. 

   379 @publishedAll	

   380 @released

   381 */

   382 const TInt KSuperSubScalingPercentage=67;

   383 

   384 /**

   385 The percentage of a font height used to calculate its baseline offset for a 

   386 superscript print position. 

   387 @publishedAll	

   388 @released

   389 */

   390 const TInt KSuperscriptOffsetPercentage=-28;

   391 

   392 /**

   393 The percentage of a font height used to calculate its baseline offset for a 

   394 subscript print position. 

   395 @publishedAll	

   396 @released

   397 */

   398 const TInt KSubscriptOffsetPercentage=14;

   399 

   400 class CFont;

   401 

   402 /** Typeface store abstract base interface.

   403 

   404 This class provides the interface to a store for typefaces.

   405 

   406 See also CFontStore. 

   407 @publishedAll

   408 @released

   409 */

   410 class CTypefaceStore : public CBase

   411 	{

   412 public:

   413 	IMPORT_C ~CTypefaceStore();

   414 

   415 	/**

   416 	Gets the font which is the nearest to the given font specification.

   417 

   418 	When the font is no longer needed, call @c ReleaseFont().

   419 

   420 	Note that this deprecated function is replaced by the new @c GetNearestFontToDesignHeightInTwips() 

   421 	yielding (virtually) the same result. However clients are strongly encouraged to use the new

   422 	@c GetNearestFontToMaxHeightInTwips() function instead. This will guarantee that every 

   423 	character within any given text string will fit within the given amount of twips, whereas the design 

   424 	height is an aesthetic unit decided by the font designer without strict physical meaning, which 

   425 	may result in cropped characters.

   426 

   427 	@param aFont On return, contains a pointer to the nearest font.

   428 	@param aFontSpec The specification of the font to be matched.

   429 	@return KErrNone if successful; a system-wide error code otherwise.

   430 	@publishedAll

   431 	@deprecated Use GetNearestFontToDesignHeightInTwips

   432 	*/

   433 	virtual TInt GetNearestFontInTwips(CFont*& aFont, const TFontSpec& aFontSpec) = 0;

   434 

   435 	/**

   436 	Gets the font which is the nearest to the given font specification.

   437 	

   438 	When the font is no longer needed, call @c ReleaseFont().

   439 

   440 	This new function replaces the deprecated @c GetNearestFontInTwips() yielding (virtually) the 

   441 	same result. However clients are strongly encouraged to use the new

   442 	@c GetNearestFontToMaxHeightInTwips() function instead. This will guarantee that every 

   443 	character within any given text string will fit within the given amount of twips, whereas the design 

   444 	height is an aesthetic unit decided by the font designer without strict physical meaning, which 

   445 	may result in cropped characters.

   446 

   447 	@param aFont On return, contains a pointer to the nearest font.

   448 	@param aFontSpec The specification of the font to be matched.

   449 	@return KErrNone if successful; a system-wide error code otherwise.

   450 	@publishedAll

   451 	@released

   452 	*/

   453 	virtual TInt GetNearestFontToDesignHeightInTwips(CFont*& aFont, const TFontSpec& aFontSpec) = 0;

   454 	

   455 	/**

   456 	Gets the font which is the nearest to the given font specification.

   457 	

   458 	When the font is no longer needed, call @c ReleaseFont().

   459 

   460 	The font and bitmap server returns a pointer to the nearest matching font 

   461 	from those available. Matches to max height of font - this does its best 

   462 	to return a font that will fit within the maximum height specified (but 

   463 	note that variations due to hinting algorithms may rarely result in this 

   464 	height being exceeded by up to one pixel). Problems can also be 

   465 	encountered with bitmap fonts where the typeface exists but doesn't have 

   466 	a font small enough.

   467 

   468 	@param aFont On return, contains a pointer to the nearest font.

   469 	@param aFontSpec The specification of the font to be matched.

   470 	@param aMaxHeight The maximum height within which the font must fit.

   471 	@return KErrNone if successful; a system-wide error code otherwise.

   472 	@publishedAll

   473 	@released

   474 	*/

   475 	virtual TInt GetNearestFontToMaxHeightInTwips(CFont*& aFont, const TFontSpec& aFontSpec, TInt aMaxHeight) = 0;

   476 

   477 	/** Gets the number of typefaces supported by the typeface store.

   478 	

   479 	@return The number of supported typefaces. */

   480 	virtual TInt NumTypefaces() const=0;

   481 

   482 	/** Gets typeface information for a specified typeface index.

   483  

   484  	This information is returned in aTypefaceSupport, and

   485 	includes the typeface name and typeface attributes, the number of font

   486  	heights, the maximum and minimum font heights, and whether it is a

   487 	scaleable typeface.

   488  

   489  	@param aTypefaceSupport On return, if the function executed successfully, 

   490  	this object contains the typeface information.

   491   	@param aTypefaceIndex A typeface index number, in the range: zero to

   492              (NumTypefaces() - 1). */

   493 	virtual void TypefaceSupport(TTypefaceSupport& aTypefaceSupport,TInt aTypefaceIndex) const=0;

   494 

   495 	/** Gets the height of the font with specified height and typeface indices, 

   496 	in twips.

   497 	

   498 	The value returned is rounded up or down to the nearest font height in twips.

   499 	

   500 	@param aTypefaceIndex A typeface index number, in the range: 0 to 

   501 	(NumTypefaces() - 1). 

   502 	@param aHeightIndex A font height index number.

   503 	@return The height of the font, in twips. */

   504 	virtual TInt FontHeightInTwips(TInt aTypefaceIndex,TInt aHeightIndex) const=0;

   505 	IMPORT_C void ReleaseFont(CFont* aFont);

   506 	IMPORT_C static TInt BaselineOffset(TInt aHeight,TFontPrintPosition aPos);

   507 	IMPORT_C static TInt SuperSubHeight(TInt aHeight,TFontPrintPosition aPos);

   508 protected:

   509 	IMPORT_C CTypefaceStore();

   510 	IMPORT_C void ConstructL();

   511 	IMPORT_C void AddFontL(CFont* aFont);

   512 	IMPORT_C TBool IncrementFontCount(const CFont* aFont);

   513 private:

   514 	TBool FindFont(const CFont* aFont, TInt& aIdx) const;

   515 	NONSHARABLE_CLASS(TFontAccess)

   516 	/**

   517 	Pairs a font with a count of how many clients of the typeface store 

   518 	are accessing that font. 

   519     */

   520 		{

   521 	public:

   522 		/** A device specific font. */

   523 		CFont* iFont;

   524 		/** The number of clients accessing the font. */

   525 		TInt iAccessCount;

   526 		};

   527 protected:

   528 	/** A list of fonts accessed by clients of the typeface store, which pairs 

   529 	a font with a count of the number of clients accessing the font.

   530 	

   531 	Implemented as an array of TFontAccess objects.

   532 	

   533 	An object is added to this array for every font accessed. If the font is 

   534 	released by all clients, and the access count drops to zero, the font is 

   535 	removed from the list. */

   536 	CArrayFixFlat<TFontAccess>* iFontAccess;

   537 	};

   538 

   539 /** The maximum number of entries in the font cache.

   540 

   541 @see CFontCache */

   542 const TInt KMaxFontCacheEntries=32;

   543 

   544 /** Font cache. 

   545 

   546 When a CFont* needs to be found for a particular TFontSpec, the cache can 

   547 be searched to see if the TFontSpec is already in the cache. If the TFontSpec 

   548 is in the cache, its corresponding CFont* can be returned. Otherwise 

   549 GetNearestFontInTwips() must be used to search all of the available fonts for 

   550 the nearest CFont- a procedure which takes much longer than a simple cache

   551 search.

   552 

   553 The current font cache should be destroyed and a new cache created whenever 

   554 the zoom factor or device map changes, as these changes break the relation 

   555 between CFont and TFontSpec. 

   556 @publishedAll

   557 @released

   558 */

   559 class CFontCache : public CBase

   560 	{

   561 public:

   562 	IMPORT_C CFontCache();

   563 	IMPORT_C CFontCache(TInt aMaxEntries);

   564 	IMPORT_C ~CFontCache();

   565 	IMPORT_C CFont* Search(const TFontSpec& aFontSpec);

   566 	IMPORT_C CFont* AddEntryL(CFont* aFont,const TFontSpec& aFontSpec);

   567 	IMPORT_C CFont* RemoveFirstEntry();

   568 public:

   569 	/** The number of cache hits since the font cache was created i.e. 

   570 	successful results from CFontCache::Search(). */

   571 	TInt iNumHits;

   572 	/** The number of cache misses since the font cache was created i.e. 

   573 	unsuccessful results from CFontCache::Search(). */

   574 	TInt iNumMisses;

   575 private:

   576 	class CFontCacheEntry : public CBase

   577 		{

   578 	public:

   579 		CFontCacheEntry(CFont* aFont,const TFontSpec& aFontSpec,CFontCacheEntry* aNext);

   580 	public:

   581 		CFont* iFont;

   582 		TFontSpec iSpec;

   583 		CFontCacheEntry* iNext;

   584 		};

   585 private:

   586 	TInt iNumEntries;

   587 	TInt iMaxEntries;

   588 	CFontCacheEntry* iFirst;

   589 	};

   590 

   591 /**

   592 WARNING: this Class is for internal use ONLY.  Compatibility is not guaranteed in future releases.

   593 UIDs corresponding to the CFont API extension functions

   594 @internalTechnology

   595 */

   596 const TUid KFontCapitalAscent	= {0x1020498E};

   597 const TUid KFontMaxAscent		= {0x10204B10};

   598 const TUid KFontStandardDescent	= {0x10204B11};

   599 const TUid KFontMaxDescent		= {0x10205AFC};

   600 const TUid KFontLineGap			= {0x10204B12};

   601 const TUid KFontGetFontTable    = {0x102872C1};

   602 const TUid KFontGetGlyphOutline = {0x102872C2};

   603 const TUid KFontReleaseGlyphOutline = {0x2002A1FD};

   604 const TUid KFontReleaseFontTable = {0x2002AC24};

   605 

   606 

   607 /** Abstract font interface.

   608 

   609 The CFont class provides a device-independent interface to a device-dependent 

   610 font usually obtained from a call to GetNearestFont...() on a graphics device. 

   611 It is used as a handle in CGraphicsContext::UseFont() and to obtain 

   612 device-dependent information about the font - notably the pixel width of a text 

   613 string.

   614 

   615 @see CFbsFont

   616 @see CGraphicsContext::UseFont() 

   617 @publishedAll 

   618 @released

   619 */

   620 class CFont : public CBase

   621 	{

   622 	friend class CTypefaceStore;

   623 public:

   624 

   625 	/** Text direction flags.

   626 

   627 	This enum is used in TMeasureTextInput and determines whether the text is 

   628 	drawn horizontally or vertically. Note: text is drawn vertically in some 

   629 	styles of Japanese, etc.

   630 

   631 	@see TMeasureTextInput */

   632 	enum TTextDirection

   633 		{

   634 	/** Text is drawn horizontally. */

   635  		/** Text is drawn horizontally. */

   636    		EHorizontal,

   637  		/** Text is drawn vertically. */

   638 		EVertical

   639 		};

   640 

   641 	/** Complicated parameter block used for contextual glyph selection, 

   642 	ligature creation and diacritic placement when drawing text in complex 

   643 	scripts

   644 

   645 	This class declares a constructor, another scoped class, and several other 

   646 	enums. However this class is unlikely to be useful to third party developers.

   647 

   648 	@see CFont::GetCharacterPosition()

   649 	@see CFont::GetCharacterPosition2()

   650 	@publishedAll

   651 	@released

   652 	*/

   653 	class TPositionParam

   654 		{

   655 	public:

   656 		/** Standard constructor. */

   657 		TPositionParam():

   658 			iDirection(EHorizontal),

   659 			iFlags(0),

   660 			iPosInText(0),

   661 			iOutputGlyphs(0)

   662 			{

   663 			}

   664 

   665 		enum

   666 			{

   667 			EMaxInputChars = 18,	// ligatures cannot be made from more than 18 components

   668 			EMaxOutputGlyphs = 8	// output can consist of up to 8 characters (one base and 7 combining characters)

   669 			};

   670 

   671 		/**Flags for TPositionParam::iFlags. */

   672 		enum TFlags

   673 			{

   674 			/** Input text is logically ordered not visually ordered. */

   675 			EFLogicalOrder = 1

   676 			};

   677 

   678 		/** Input: Orientation (EHorizontal or EVertical) in which to draw

   679 		the text. */

   680 		TInt16 iDirection;

   681 		/** Input: Flags from TFlags. */

   682 		TUint16 iFlags;

   683 		/** Input: Text containing the characters to be positioned. */

   684 		TPtrC iText;

   685 

   686 		/** Input and output: Position within iText to shape. On exit

   687 		it will index the first character not positioned */

   688 		TInt iPosInText;

   689 		/** Input and output: Pen position. */

   690 		TPoint iPen;			

   691 

   692 		/** Output of GetCharacterPosition and GetCharacterPosition2.

   693 		@see CFont::GetCharacterPosition

   694 		@see CFont::GetCharacterPosition2

   695 		@publishedAll

   696 		@released */

   697 		class TOutput

   698 			{

   699 		public:

   700 			/** Standard constructor. */

   701 			TOutput() : iBitmapSize(TSize::EUninitialized),

   702 				iBounds(TRect::EUninitialized) {}

   703 			/** Character or glyph code. */

   704 			TUint iCode;			

   705 			/** Bitmap data for the glyph, if available */

   706 			const TUint8* iBitmap;	

   707 			/** Size of the bitmap before algorithmic bolding, size 

   708 			multiplication, etc. */

   709 			TSize iBitmapSize;		

   710 			/** Bitmap bounds relative to the original pen position. */

   711 			TRect iBounds;			

   712 			};

   713 

   714 		/** Information about the glyphs that were output. */

   715 		TOutput iOutput[EMaxOutputGlyphs];	

   716 		/** Number of glyphs actually output. */

   717 		TInt iOutputGlyphs;					

   718 		};	

   719 

   720 

   721 	/** Input parameter block.

   722 

   723 	This is optionally used by CFont::MeasureText(), which is the powerful text 

   724 	measurement function underlying all the other text measurement functions.

   725 

   726 	@see CFont::MeasureText() 

   727 	@publishedAll

   728 	@released

   729 	*/

   730 	class TMeasureTextInput

   731 		{

   732 	public:

   733 		TMeasureTextInput():

   734 			iStartInputChar(0),

   735 			iEndInputChar(KMaxTInt),

   736 			iDirection(EHorizontal),

   737 			iFlags(0),

   738 			iMaxAdvance(KMaxTInt),

   739 			iMaxBounds(KMaxTInt),

   740 			iCharJustNum(0),

   741 			iCharJustExcess(0),

   742 			iWordJustNum(0),

   743 			iWordJustExcess(0)

   744 			{

   745 			}

   746 

   747 		/**Flags for TMeasureTextInput::iFlags. */

   748 		enum TFlags

   749 			{

   750  			/** Input text is visually ordered left-to-right. */

   751  			EFVisualOrder = 1,

   752  			/** Input text is visually ordered right-to-left.

   753  			Overrides EFVisualOrder. */

   754  			EFVisualOrderRightToLeft = 2,

   755  			/** Flag to consider side bearings when checking bounds for line-break */

   756  			EFIncludePenPositionInBoundsCheck = 4

   757 			};

   758 

   759 		/** Starting index specifying first input character in iText.

   760 	

   761 		Together with iEndInputChar, this allows some context before and 

   762 		after the measured text to be supplied so that shaping can work 

   763 		properly. */

   764 		TInt iStartInputChar;	

   765 	

   766 		/** Index specifying the final input character.

   767 	

   768 		Together with iStartInputChar, this allows some context before and 

   769 		after the measured text to be supplied so that shaping can work 

   770 		properly. */

   771 		TInt iEndInputChar;		

   772 	

   773 		/** The direction in which to draw the text. */

   774 		TUint16 iDirection;

   775 	

   776 		/** Flags from TFlags. */

   777 		TUint16 iFlags;

   778 	

   779 		/** The maximum advance. */

   780 		TInt iMaxAdvance;		

   781 		

   782 		/** The maximum width (or height if drawing vertically) of bounds. */

   783 		TInt iMaxBounds;		

   784 	

   785 		/** The number of glyph groups to be letter-spaced. */

   786 		TInt iCharJustNum;		

   787 	

   788 		/** The amount of space to be used for letter spacing. */

   789 		TInt iCharJustExcess;	

   790 		

   791 		/** The number of spaces to be used for word spacing. */

   792 		TInt iWordJustNum;		

   793 	

   794 		/** The amount of space to be used for word spacing. */

   795 		TInt iWordJustExcess;	

   796 		};

   797 

   798 	/** Output parameter block.

   799 

   800 	This is optionally used by CFont::MeasureText(), which is the powerful text 

   801 	measurement function underlying all the other text measurement functions.

   802 

   803 	@see CFont::MeasureText() 

   804 	@publishedAll

   805 	@released

   806 	*/

   807 	class TMeasureTextOutput

   808 		{

   809 		public:

   810 		/** The number of input characters that would be drawn.

   811 	

   812 		This may be less than the length of the text if a maximum advance or bounding 

   813 		box size is specified. */

   814 		TInt iChars;			

   815 		/** The number of glyphs that would be drawn. */

   816 		TInt iGlyphs;			

   817 		/** The number of groups that would be drawn.

   818 	

   819 		A group is a base glyph plus one or more combining characters. */

   820 		TInt iGroups;			

   821 		/** The number of word spaces (U+0020) that would be drawn. */

   822 		TInt iSpaces;			

   823 		/** The bounding box of all the glyphs that would be drawn. */

   824 		TRect iBounds;			

   825 		/** The maximum width and height of any glyph. */

   826 		TSize iMaxGlyphSize;	

   827 		};

   828 

   829 	/**

   830 	Data availability flags.

   831 

   832 	Some fonts like printer fonts may only have width information and can return 

   833 	ECharacterWidthOnly to show this: the text drawing routines in CFont synthesize 

   834 	the rest of the data if necessary.

   835 

   836 	@see GetCharacterData() 

   837 	@publishedAll	

   838 	@released

   839 	*/

   840 	enum TCharacterDataAvailability

   841 		{

   842 		/** No font information available. */

   843 		ENoCharacterData,

   844 		/** Width information only is available. */

   845 		ECharacterWidthOnly,

   846 		/** All character data is available. */

   847 		EAllCharacterData

   848 		};

   849 

   850 private:

   851 	// virtual functions have been made protected and public non-virtual ones

   852 	// added to convert CFont to a handle-body pattern. SC is kept throught the

   853 	// new functions and BC is kept by keeping the protected functions in the

   854 	// same place in the class, and therefore in the same place in the vtable

   855 	/**

   856 	@publishedAll

   857 	WARNING: Function for internal use ONLY.  Compatibility is not guaranteed in future releases. Please see derived class for implementation.

   858 	*/

   859 	virtual TUid DoTypeUid() const=0;

   860 	/**

   861 	@publishedAll

   862 	WARNING: Function for internal use ONLY.  Compatibility is not guaranteed in future releases. Please see derived class for implementation.

   863 	*/

   864 	virtual TInt DoHeightInPixels() const=0;

   865 	/**

   866 	@publishedAll

   867 	WARNING: Function for internal use ONLY.  Compatibility is not guaranteed in future releases. Please see derived class for implementation.

   868 	*/

   869 	virtual TInt DoAscentInPixels() const=0;

   870 	IMPORT_C virtual TInt DoDescentInPixels() const;

   871 	/**

   872 	@publishedAll

   873 	WARNING: Function for internal use ONLY.  Compatibility is not guaranteed in future releases. Please see derived class for implementation.

   874 	*/

   875 	virtual TInt DoCharWidthInPixels(TChar aChar) const=0;

   876 	/**

   877 	@publishedAll

   878 	WARNING: Function for internal use ONLY.  Compatibility is not guaranteed in future releases. Please see derived class for implementation.

   879 	*/

   880 	virtual TInt DoTextWidthInPixels(const TDesC& aText) const=0;

   881 	/**

   882 	@publishedAll

   883 	WARNING: Function for internal use ONLY.  Compatibility is not guaranteed in future releases. Please see derived class for implementation.

   884 	*/

   885 	virtual TInt DoBaselineOffsetInPixels() const=0;

   886 	/**

   887 	@publishedAll

   888 	WARNING: Function for internal use ONLY.  Compatibility is not guaranteed in future releases. Please see derived class for implementation.

   889 	*/

   890 	virtual TInt DoTextCount(const TDesC& aText,TInt aWidthInPixels) const=0;

   891 	/**

   892 	@publishedAll

   893 	WARNING: Function for internal use ONLY.  Compatibility is not guaranteed in future releases. Please see derived class for implementation.

   894 	*/

   895 	virtual TInt DoTextCount(const TDesC& aText,TInt aWidthInPixels,TInt& aExcessWidthInPixels) const=0;

   896 	/**

   897 	@publishedAll

   898 	WARNING: Function for internal use ONLY.  Compatibility is not guaranteed in future releases. Please see derived class for implementation.

   899 	*/

   900 	virtual TInt DoMaxCharWidthInPixels() const=0;

   901 	/**

   902 	@publishedAll

   903 	WARNING: Function for internal use ONLY.  Compatibility is not guaranteed in future releases. Please see derived class for implementation.

   904 	*/

   905 	virtual TInt DoMaxNormalCharWidthInPixels() const=0;

   906 	/**

   907 	@publishedAll

   908 	WARNING: Function for internal use ONLY.  Compatibility is not guaranteed in future releases. Please see derived class for implementation.

   909 	*/

   910 	virtual TFontSpec DoFontSpecInTwips() const=0;

   911 

   912 protected:	

   913 	IMPORT_C virtual TCharacterDataAvailability DoGetCharacterData(TUint aCode, TOpenFontCharMetrics& aMetrics,const TUint8*& aBitmap,TSize& aBitmapSize) const;

   914 	IMPORT_C virtual TBool DoGetCharacterPosition(TPositionParam& aParam) const;

   915 	IMPORT_C virtual TInt DoExtendedFunction(TUid aFunctionId, TAny* aParam = NULL) const;

   916 

   917 protected:

   918 	IMPORT_C virtual ~CFont();

   919 

   920 public:

   921 	inline TInt FontCapitalAscent() const;

   922 	inline TInt FontMaxAscent() const;

   923 	inline TInt FontStandardDescent() const;

   924 	inline TInt FontMaxDescent() const;

   925 	inline TInt FontLineGap() const;

   926 	inline TInt FontMaxHeight() const;

   927 

   928 public:

   929 	/** Gets run-time identity of the actual font type. This enables safe casting to 

   930 	a derived type.

   931 	

   932 	For example, if the derived type is a CFbsFont, the return value is KCFbsFontUid. 

   933 	You would need to cast to a CFbsFont to get a character bounding box. Similarly, 

   934 	a CBitmapFont returns KCBitmapFontUidVal.

   935 	

   936 	@return The font-type identifier. */

   937 	IMPORT_C TUid TypeUid() const;

   938 

   939 	/** Gets the font height in pixels.

   940 	Note that this deprecated function is replaced by the new @c FontMaxHeight().

   941 

   942 	@return The font height in pixels.

   943 	@see FontMaxHeight()

   944 	@deprecated */

   945 	IMPORT_C TInt HeightInPixels() const;

   946 

   947 	/** Gets the font ascent in pixels.

   948 	Note that this deprecated function is replaced by the new @c FontMaxAscent()

   949 	or in some cases @c FontCapitalAscent().	

   950 	

   951 	@return The font ascent in pixels.

   952 	@see FontCapitalAscent()

   953 	@see FontMaxAscent()

   954 	@deprecated */

   955 	IMPORT_C TInt AscentInPixels() const;

   956 	

   957 	/** Gets the font descent in pixels.

   958 	Note that this deprecated function is replaced by the new @c FontMaxDescent()

   959 	or in some cases @c FontStandardDescent().	

   960 	

   961 	@return The font descent in pixels.

   962 	@see FontStandardDescent() 

   963 	@see FontMaxDescent()

   964 	@deprecated */

   965 	IMPORT_C TInt DescentInPixels() const;

   966 

   967 	/** Gets the width in pixels in this font of the specified character.

   968 	

   969 	Note: For OpenType fonts this function returns the horizontal advance of

   970 	the character, which may be different from the actual width.

   971 	

   972 	@param aChar The character whose width should be determined. 

   973 	@return The width in pixels of the specified character in this font. */

   974 	IMPORT_C TInt CharWidthInPixels(TChar aChar) const;

   975 

   976 	/** Gets the width in pixels of the specified descriptor when displayed in this 

   977 	font.

   978 	

   979 	@param aText The descriptor whose width should be determined. 

   980 	@return The width of the specified descriptor when displayed in this font, 

   981 	in pixels. */

   982 	IMPORT_C TInt TextWidthInPixels(const TDesC& aText) const;

   983 

   984 	/** Gets the baseline offset in pixels. 

   985 	

   986 	The baseline offset is how far a font is raised or lowered from its normal 

   987 	baseline.

   988 	

   989 	@return Offset from normal baseline, in pixels. */

   990 	IMPORT_C TInt BaselineOffsetInPixels() const;

   991 

   992 	/** Gets how much of the specified descriptor can be displayed in this font without 

   993 	exceeding the specified width.

   994 	

   995 	Note:

   996 	

   997 	This function does not display any of the descriptor itself - it is used 

   998 	before display, to test whether the whole descriptor can be displayed.

   999 	

  1000 	@param aText The descriptor. 

  1001 	@param aWidthInPixels The available width for character display. 

  1002 	@return The number of characters which will be able to be displayed without 

  1003 	exceeding the specified width. The count starts from the beginning of the 

  1004 	descriptor. */

  1005 	IMPORT_C TInt TextCount(const TDesC& aText,TInt aWidthInPixels) const;

  1006 

  1007 	/** Gets how much of the specified descriptor can be displayed in this font without 

  1008 	exceeding the specified width. 

  1009 	

  1010 	It also returns the excess width - defined as the specified available width 

  1011 	minus the width of the portion of the descriptor which can be displayed without 

  1012 	exceeding the available width.

  1013 	

  1014 	@param aText The descriptor. 

  1015 	@param aWidthInPixels The available width for character display. 

  1016 	@param aExcessWidthInPixels The excess width after displaying the portion of 

  1017 	the descriptor, in pixels. 

  1018 	@return The number of characters which will be able to be displayed without 

  1019 	exceeding the specified width. The count starts from the beginning of the 

  1020 	descriptor. */

  1021 	IMPORT_C TInt TextCount(const TDesC& aText,TInt aWidthInPixels,TInt& aExcessWidthInPixels) const;

  1022 

  1023 	/** Gets the width in pixels of the widest character in this font.

  1024 	

  1025 	@return The width of the maximum width character, in pixels. */

  1026 	IMPORT_C TInt MaxCharWidthInPixels() const;

  1027 

  1028 	/** Gets the width in pixels of the widest normal character in this font.

  1029 	

  1030 	Normal characters include all character in a character set except non-alphabetic 

  1031 	characters (e.g. the copyright symbol, or a block graphics symbol, for example).

  1032 	

  1033 	@return The width of the maximum width normal character, in pixels. */

  1034 	IMPORT_C TInt MaxNormalCharWidthInPixels() const;

  1035 

  1036 	/** Gets the font specification of this font in twips.

  1037 	

  1038 	@return The font specification of this font (in twips). */

  1039 	IMPORT_C TFontSpec FontSpecInTwips() const;

  1040 	IMPORT_C TCharacterDataAvailability GetCharacterData(TUint aCode, TOpenFontCharMetrics& aMetrics,const TUint8*& aBitmap,TSize& aBitmapSize) const;

  1041 	IMPORT_C TBool GetCharacterPosition(TPositionParam& aParam) const;

  1042 	IMPORT_C TInt WidthZeroInPixels() const;

  1043 	IMPORT_C TInt MeasureText(const TDesC& aText, const TMeasureTextInput* aInput = NULL, TMeasureTextOutput* aOutput = NULL) const;

  1044 	IMPORT_C static TBool CharactersJoin(TInt aLeftCharacter, TInt aRightCharacter);

  1045 	IMPORT_C TInt ExtendedFunction(TUid aFunctionId, TAny* aParam = NULL) const;

  1046 	IMPORT_C TBool GetCharacterPosition2(TPositionParam& aParam, RShapeInfo& aShapeInfo) const;

  1047 

  1048 	/** Gets the width in pixels of the specified descriptor when displayed in this 

  1049 	font.

  1050 	

  1051 	@param aText The descriptor whose width should be determined.

  1052 	@param aParam Parameter block that controls how much of aText is measured

  1053 	@return The width of the specified descriptor when displayed in this font, 

  1054 	in pixels. */

  1055 	IMPORT_C TInt TextWidthInPixels(const TDesC& aText,const TMeasureTextInput* aParam) const;

  1056 	};

  1057 

  1058 

  1059 // inline functions from original gdi.inl

  1060 /** Gets the ascent of an ANSI capital letter in the font whether or not

  1061 there are any ANSI capitals in the font.

  1062 @return The positive distance from the font baseline to the top of a

  1063 standard ANSI capital letter

  1064 @publishedAll

  1065 @released

  1066 */

  1067 inline TInt CFont::FontCapitalAscent() const

  1068     {

  1069     return ExtendedFunction(KFontCapitalAscent);

  1070     }

  1071 

  1072 /** Gets the max ascent of any pre-composed glyph in the font. This will

  1073 include accents or diacritics that form part of pre-composed glyphs. It is

  1074 not guaranteed to cover the max ascent of composite glyphs that have to be

  1075 created by a layout engine. This is also the recommended distance between

  1076 the top of a text box and the baseline of the first line of text. 

  1077 @return The positive distance from the font baseline to the top of the

  1078 highest pre-composed glyph (including accents) above the baseline

  1079 @publishedAll

  1080 @released

  1081 */

  1082 inline TInt CFont::FontMaxAscent() const

  1083     {

  1084     return ExtendedFunction(KFontMaxAscent);

  1085     }

  1086 

  1087 /** Gets the descent of an ANSI descending character in the font.

  1088 Whether or not there are any ANSI descenders in the font.

  1089 @return The positive distance from the font baseline to the bottom of the

  1090 lowest ANSI descender

  1091 @publishedAll

  1092 @released

  1093 */

  1094 inline TInt CFont::FontStandardDescent() const

  1095     {

  1096     return ExtendedFunction(KFontStandardDescent);

  1097     }

  1098 

  1099 /** Gets the max descent of any pre-composed glyph in the font. This will

  1100 include accents or diacritics that form part of pre-composed glyphs. It is

  1101 not guaranteed to cover the max descent of composite glyphs that have to be

  1102 created by a layout engine.

  1103 @return The positive distance from the font baseline to the bottom of the

  1104 lowest pre-composed glyph (including accents) below the baseline

  1105 @publishedAll

  1106 @released

  1107 */

  1108 inline TInt CFont::FontMaxDescent() const

  1109     {

  1110     return ExtendedFunction(KFontMaxDescent);

  1111     }

  1112 

  1113 /** Gets the suggested line gap for the font. This is the recommended

  1114 baseline to baseline distance between successive lines of text in the font.

  1115 @return The positive recommended gap between successive lines

  1116 @publishedAll

  1117 @released

  1118 */

  1119 inline TInt CFont::FontLineGap() const

  1120     {

  1121     return ExtendedFunction(KFontLineGap);

  1122     }

  1123 

  1124 /**

  1125 Gets the (positive) maximum height in pixels of the font.

  1126 This may differ from the design height.

  1127 

  1128 @return The maximum height of the font.

  1129 @publishedAll

  1130 @released

  1131 */

  1132 inline TInt CFont::FontMaxHeight() const

  1133     {

  1134     return FontMaxAscent() + FontMaxDescent();