CFont Class Reference

#include <gdi.h>

Link against: gdi.lib

class CFont : public CBase

Inherits from

CFont

Nested Classes and Structures

Public Member Enumerations
enum	TCharacterDataAvailability { ENoCharacterData, ECharacterWidthOnly, EAllCharacterData }
enum	TTextDirection { EHorizontal, EVertical }

Public Member Functions
IMPORT_C TInt	AscentInPixels()
IMPORT_C TInt	BaselineOffsetInPixels()
IMPORT_C TInt	CharWidthInPixels(TChar)
IMPORT_C TBool	CharactersJoin(TInt, TInt)
IMPORT_C TInt	DescentInPixels()
IMPORT_C TInt	ExtendedFunction(TUid, TAny *)
TInt	FontCapitalAscent()
TInt	FontLineGap()
TInt	FontMaxAscent()
TInt	FontMaxDescent()
TInt	FontMaxHeight()
IMPORT_C TFontSpec	FontSpecInTwips()
TInt	FontStandardDescent()
IMPORT_C TCharacterDataAvailability	GetCharacterData(TUint, TOpenFontCharMetrics &, const TUint8 *&, TSize &)
IMPORT_C TBool	GetCharacterPosition(TPositionParam &)
IMPORT_C TBool	GetCharacterPosition2(TPositionParam &, RShapeInfo &)
IMPORT_C TInt	HeightInPixels()
IMPORT_C TInt	MaxCharWidthInPixels()
IMPORT_C TInt	MaxNormalCharWidthInPixels()
IMPORT_C TInt	MeasureText(const TDesC &, const TMeasureTextInput , TMeasureTextOutput )
IMPORT_C TInt	TextCount(const TDesC &, TInt)
IMPORT_C TInt	TextCount(const TDesC &, TInt, TInt &)
IMPORT_C TInt	TextWidthInPixels(const TDesC &)
IMPORT_C TInt	TextWidthInPixels(const TDesC &, const TMeasureTextInput *)
IMPORT_C TUid	TypeUid()
IMPORT_C TInt	WidthZeroInPixels()

Protected Member Functions
virtual	~CFont()
virtual IMPORT_C TInt	DoExtendedFunction(TUid, TAny *)
virtual IMPORT_C TCharacterDataAvailability	DoGetCharacterData(TUint, TOpenFontCharMetrics &, const TUint8 *&, TSize &)
virtual IMPORT_C TBool	DoGetCharacterPosition(TPositionParam &)

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

Detailed Description

Abstract font interface.

The CFont class provides a device-independent interface to a device-dependent font usually obtained from a call to GetNearestFont...() on a graphics device. It is used as a handle in CGraphicsContext::UseFont() and to obtain device-dependent information about the font - notably the pixel width of a text string.

See also: CFbsFont CGraphicsContext::UseFont()

Member Enumeration Documentation

Enum TCharacterDataAvailability

Data availability flags.

Some fonts like printer fonts may only have width information and can return ECharacterWidthOnly to show this: the text drawing routines in CFont synthesize the rest of the data if necessary.

Enumerator	Value	Description
ENoCharacterData		No font information available.
ECharacterWidthOnly		Width information only is available.
EAllCharacterData		All character data is available.

Enum TTextDirection

Text direction flags.

This enum is used in TMeasureTextInput and determines whether the text is drawn horizontally or vertically. Note: text is drawn vertically in some styles of Japanese, etc.

Enumerator	Value	Description
EHorizontal		Text is drawn horizontally. Text is drawn horizontally.
EVertical		Text is drawn vertically.

Constructor & Destructor Documentation

~CFont ( )

IMPORT_C

~CFont

(

)

[protected, virtual]

Default destructor.

Member Function Documentation

AscentInPixels ( )

IMPORT_C TInt

AscentInPixels

(

)

const

Gets the font ascent in pixels. Note that this deprecated function is replaced by the new FontMaxAscent() or in some cases FontCapitalAscent().

Deprecated

Returns: The font ascent in pixels.

BaselineOffsetInPixels ( )

IMPORT_C TInt

BaselineOffsetInPixels

(

)

const

Gets the baseline offset in pixels.

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

Returns: Offset from normal baseline, in pixels.

CharWidthInPixels ( TChar )

IMPORT_C TInt

CharWidthInPixels

(

TChar

aChar

)

const

Gets the width in pixels in this font of the specified character.

Note: For OpenType fonts this function returns the horizontal advance of the character, which may be different from the actual width.

Parameter	Description
aChar	The character whose width should be determined.

Returns: The width in pixels of the specified character in this font.

CharactersJoin ( TInt, TInt )

IMPORT_C TBool	CharactersJoin	(	TInt	aLeftCharacter,
			TInt	aRightCharacter
		)	[static]

Determines if aLeftCharacter and aRightCharacter affect each other's contextual glyph form if placed next to each other. If either character is a combining character, EFalse will be returned, which is not generally useful information. Pass in base characters ignoring intervening combining characters.

Parameter	Description
aLeftCharacter	Unicode code for the character that stands on the left.
aRightCharacter	Unicode code for the character that stands on the right.

Returns: EFalse if the characters do not affect the contextual glyphs that are be chosen when the two are rendered together, compared to being separated (for example by a space).

DescentInPixels ( )

IMPORT_C TInt

DescentInPixels

(

)

const

Gets the font descent in pixels. Note that this deprecated function is replaced by the new FontMaxDescent() or in some cases FontStandardDescent().

Deprecated

Returns: The font descent in pixels.

DoExtendedFunction ( TUid, TAny * )

IMPORT_C TInt	DoExtendedFunction	(	TUid	aFunctionId,
			TAny *	aParam = NULL
		)	const [protected, virtual]

API extension system that enables the caller to access a particular API extension function. N.B. Any overload of this function in a derived class should call its immediate parent implementation for any extension function Uid that it does not recognize and handle.

Parameter	Description
aParam	Pointer to an arbitrary parameter block that can be used to provide and/or return information to/from the particular extension function, defaults to NULL.

Returns: Integer return value from extension function

DoGetCharacterData ( TUint, TOpenFontCharMetrics &, const TUint8 *&, TSize & )

IMPORT_C TCharacterDataAvailability	DoGetCharacterData	(	TUint	aCode,
			TOpenFontCharMetrics &	aMetrics,
			const TUint8 *&	aBitmap,
			TSize &	aBitmapSize
		)	const [protected, virtual]

Gets the character metrics for a character.

Parameter	Description
aCode	The character code.
aMetrics	On return, contains the character bitmap.
aBitmap	On return, this points to NULL.
aBitmapSize	On return, this has a size of (0,0).

Returns: ECharacterWidthOnly

DoGetCharacterPosition ( TPositionParam & )

IMPORT_C TBool

DoGetCharacterPosition

(

TPositionParam &

aParam

)

const [protected, virtual]

Overridable function innards of GetCharacterPosition and GetCharacterPosition2. It is generally not useful to override this function.

ExtendedFunction ( TUid, TAny * )

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

Enables the caller to access a particular API extension function. N.B. Any overload of this function in a derived class should call its immediate parent implementation for any extension function UID that it does not recognize and handle.

Parameter	Description
aFunctionId	UID of the required extension function
aParam	Pointer to an arbitrary parameter block that can be used to provide and/or return information to/from the particular extension function, defaults to NULL.

Returns: Integer return value from extension function

FontCapitalAscent ( )

TInt

FontCapitalAscent

(

)

const [inline]

Gets the ascent of an ANSI capital letter in the font whether or not there are any ANSI capitals in the font.

Returns: The positive distance from the font baseline to the top of a standard ANSI capital letter

FontLineGap ( )

TInt

FontLineGap

(

)

const [inline]

Gets the suggested line gap for the font. This is the recommended baseline to baseline distance between successive lines of text in the font.

Returns: The positive recommended gap between successive lines

FontMaxAscent ( )

TInt

FontMaxAscent

(

)

const [inline]

Gets the max ascent of any pre-composed glyph in the font. This will include accents or diacritics that form part of pre-composed glyphs. It is not guaranteed to cover the max ascent of composite glyphs that have to be created by a layout engine. This is also the recommended distance between the top of a text box and the baseline of the first line of text.

Returns: The positive distance from the font baseline to the top of the highest pre-composed glyph (including accents) above the baseline

FontMaxDescent ( )

TInt

FontMaxDescent

(

)

const [inline]

Gets the max descent of any pre-composed glyph in the font. This will include accents or diacritics that form part of pre-composed glyphs. It is not guaranteed to cover the max descent of composite glyphs that have to be created by a layout engine.

Returns: The positive distance from the font baseline to the bottom of the lowest pre-composed glyph (including accents) below the baseline

FontMaxHeight ( )

TInt

FontMaxHeight

(

)

const [inline]

Gets the (positive) maximum height in pixels of the font. This may differ from the design height.

Returns: The maximum height of the font.

FontSpecInTwips ( )

IMPORT_C TFontSpec

FontSpecInTwips

(

)

const

Gets the font specification of this font in twips.

Returns: The font specification of this font (in twips).

FontStandardDescent ( )

TInt

FontStandardDescent

(

)

const [inline]

Gets the descent of an ANSI descending character in the font. Whether or not there are any ANSI descenders in the font.

Returns: The positive distance from the font baseline to the bottom of the lowest ANSI descender

GetCharacterData ( TUint, TOpenFontCharMetrics &, const TUint8 *&, TSize & )

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

Gets the character metrics for a character.

Parameter	Description
aCode	The character code.
aMetrics	On return, contains the character bitmap.
aBitmap	On return, this points to NULL.
aBitmapSize	On return, this has a size of (0,0).

Returns: ECharacterWidthOnly

GetCharacterPosition ( TPositionParam & )

IMPORT_C TBool

GetCharacterPosition

(

TPositionParam &

aParam

)

const

Transforms one cluster of characters (base character plus combining marks, ligature or indic syllable) into one cluster of glyphs together with their positions. Repeated calls of this function (for the same input text) are considerably slower than repeated calls of GetCharacterPosition2 for Indic text (such as Hindi), as GetCharacterPosition2 can cache information between calls.

Parameter	Description
aParam	Input and output parameters

GetCharacterPosition2 ( TPositionParam &, RShapeInfo & )

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

Takes Unicode text and produces the glyph cluster for the first character in that text plus any combining mark characters, or for the first indic syllable. It is responsible for contextual glyph selection, ligature creation and diacritic placement.

Parameter	Description
aParam	The input/output parameter of the text/glyph data for the algorithm.
aShapeInfo	The function will cache "shaped" text (e.g. complex scripts such as Devanagari) here. aShapeInfo must be freshly-constructed or closed for each new piece of text in aParam.iText. If aParam.iText is unchanged between calls, aShapeInfo should be passed back in unchanged as well.

HeightInPixels ( )

IMPORT_C TInt

HeightInPixels

(

)

const

Gets the font height in pixels. Note that this deprecated function is replaced by the new FontMaxHeight().

MaxCharWidthInPixels ( )

IMPORT_C TInt

MaxCharWidthInPixels

(

)

const

Gets the width in pixels of the widest character in this font.

Returns: The width of the maximum width character, in pixels.

MaxNormalCharWidthInPixels ( )

IMPORT_C TInt

MaxNormalCharWidthInPixels

(

)

const

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

Normal characters include all character in a character set except non-alphabetic characters (e.g. the copyright symbol, or a block graphics symbol, for example).

Returns: The width of the maximum width normal character, in pixels.

MeasureText ( const TDesC &, const TMeasureTextInput , TMeasureTextOutput )

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

Text measurement function.

This is a powerful text measurement function underlying all the other text measurement functions. It takes optional input and output parameter blocks, which may be null, and returns the advance width (change in pen position when drawn horizontally) of the text, or the advance height, if the text is drawn vertically.

Some of the functions that can be performed using this function are listed below. Many of them are used by the Text Views API to do its typographic layout.

Get the advance width or advance height (return value). The advance width is the amount by which the pen advances when drawing the text horizontally, while the advance height is the amount by which the pen advances when drawing the text vertically.
Measure some text in context, so that shaping behaviour (e.g. in Arabic) can be affected by what comes before and after the text. Do this using TMeasureTextInput::iStartInputChar and TMeasureTextInput::iEndInputChar to tell the function where to start and end in the supplied descriptor.
Determine how much text fits a given size by setting TMeasureTextInput::iMaxAdvance or TMeasureTextInput::iMaxBounds.
Specify letter spacing and word spacing using TMeasureTextInput::iCharJustNum, TMeasureTextInput::iCharJustExcess, TMeasureTextInput::iWordJustNum and TMeasureTextInput::iWordJustExcess.
Get the number of characters drawn in TMeasureTextOutput::iChars when applying the various constraints in TMeasureTextInput.
Get the number of glyphs drawn in TMeasureTextOutput::iGlyphs.
Get the number of groups (formed by ligation or diacritic placement) in TMeasureTextOutput::iGroups. Groups are units of cursor movement: the cursor hops over a character-plus-accent group or an Arabic or other ligature in one go.
Get the number of word spaces in TMeasureTextOutput::iSpaces.
Get the bounds of the inked-in pixels in TMeasureTextOutput::iBounds.
Get the size of the biggest glyph that would be drawn in TMeasureTextOutput::iMaxGlyphSize.

panic: GDI 1 In debug builds only, if TMeasureTextInput::iStartInputChar is negative.

Parameter	Description
aText	The text to be measured.
aInput	The input block. This may be NULL.
aOutput	The output block. This may be NULL.

Returns: The advance width if the text is drawn horizontally or the advance height if the text is drawn vertically.

TextCount ( const TDesC &, TInt )

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

Gets how much of the specified descriptor can be displayed in this font without exceeding the specified width.

Note:

This function does not display any of the descriptor itself - it is used before display, to test whether the whole descriptor can be displayed.

Parameter	Description
aText	The descriptor.
aWidthInPixels	The available width for character display.

Returns: The number of characters which will be able to be displayed without exceeding the specified width. The count starts from the beginning of the descriptor.

TextCount ( const TDesC &, TInt, TInt & )

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

Gets how much of the specified descriptor can be displayed in this font without exceeding the specified width.

It also returns the excess width - defined as the specified available width minus the width of the portion of the descriptor which can be displayed without exceeding the available width.

Parameter	Description
aText	The descriptor.
aWidthInPixels	The available width for character display.
aExcessWidthInPixels	The excess width after displaying the portion of the descriptor, in pixels.

Returns: The number of characters which will be able to be displayed without exceeding the specified width. The count starts from the beginning of the descriptor.

TextWidthInPixels ( const TDesC & )

IMPORT_C TInt

TextWidthInPixels

(

const TDesC &

aText

)

const

Gets the width in pixels of the specified descriptor when displayed in this font.

Parameter	Description
aText	The descriptor whose width should be determined.

Returns: The width of the specified descriptor when displayed in this font, in pixels.

TextWidthInPixels ( const TDesC &, const TMeasureTextInput * )

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

Gets the width in pixels of the specified descriptor when displayed in this font.

Parameter	Description
aText	The descriptor whose width should be determined.
aParam	Parameter block that controls how much of aText is measured

Returns: The width of the specified descriptor when displayed in this font, in pixels.

TypeUid ( )

IMPORT_C TUid

TypeUid

(

)

const

Gets run-time identity of the actual font type. This enables safe casting to a derived type.

For example, if the derived type is a CFbsFont, the return value is KCFbsFontUid. You would need to cast to a CFbsFont to get a character bounding box. Similarly, a CBitmapFont returns KCBitmapFontUidVal.

Returns: The font-type identifier.

WidthZeroInPixels ( )

IMPORT_C TInt

WidthZeroInPixels

(

)

const

Gets the width of the zero character of this font in pixels.

This function is provided as the "0" character is roughly the average width of the characters of any font.

Returns: The width of the "0" character, in pixels.

CFont Class Reference

Inherits from

Nested Classes and Structures

Detailed Description

Member Enumeration Documentation

Enum TCharacterDataAvailability

Enum TTextDirection

Constructor & Destructor Documentation

~CFont ( )

Member Function Documentation

AscentInPixels ( )

BaselineOffsetInPixels ( )

CharWidthInPixels ( TChar )

CharactersJoin ( TInt, TInt )

DescentInPixels ( )

DoExtendedFunction ( TUid, TAny * )

DoGetCharacterData ( TUint, TOpenFontCharMetrics &, const TUint8 *&, TSize & )

DoGetCharacterPosition ( TPositionParam & )

ExtendedFunction ( TUid, TAny * )

FontCapitalAscent ( )

FontLineGap ( )

FontMaxAscent ( )

FontMaxDescent ( )

FontMaxHeight ( )

FontSpecInTwips ( )

FontStandardDescent ( )

GetCharacterData ( TUint, TOpenFontCharMetrics &, const TUint8 *&, TSize & )

GetCharacterPosition ( TPositionParam & )

GetCharacterPosition2 ( TPositionParam &, RShapeInfo & )

HeightInPixels ( )

MaxCharWidthInPixels ( )

MaxNormalCharWidthInPixels ( )

MeasureText ( const TDesC &, const TMeasureTextInput *, TMeasureTextOutput * )

TextCount ( const TDesC &, TInt )

TextCount ( const TDesC &, TInt, TInt & )

TextWidthInPixels ( const TDesC & )

TextWidthInPixels ( const TDesC &, const TMeasureTextInput * )

TypeUid ( )

WidthZeroInPixels ( )

MeasureText ( const TDesC &, const TMeasureTextInput , TMeasureTextOutput )