Abstract font interface. More...

#include <gdi.h>

Inheritance diagram for CFont:

Classes
class	TMeasureTextInput
	Input parameter block. More...

class	TMeasureTextOutput
	Output parameter block. More...

class	TPositionParam
	Complicated parameter block used for contextual glyph selection, ligature creation and diacritic placement when drawing text in complex scripts. More...

Public Types
enum	TTextDirection { EHorizontal , EVertical }
	Text direction flags. More...

enum	TCharacterDataAvailability { ENoCharacterData , ECharacterWidthOnly , EAllCharacterData }

Public Member Functions
TInt	FontCapitalAscent () const
	Gets the ascent of an ANSI capital letter in the font whether or not there are any ANSI capitals in the font.

TInt	FontMaxAscent () const
	Gets the max ascent of any pre-composed glyph in the font.

TInt	FontStandardDescent () const
	Gets the descent of an ANSI descending character in the font.

TInt	FontMaxDescent () const
	Gets the max descent of any pre-composed glyph in the font.

TInt	FontLineGap () const
	Gets the suggested line gap for the font.

TInt	FontMaxHeight () const
	Gets the (positive) maximum height in pixels of the font.

IMPORT_C TUid	TypeUid () const
	Gets run-time identity of the actual font type.

IMPORT_C TInt	HeightInPixels () const
	Gets the font height in pixels.

IMPORT_C TInt	AscentInPixels () const
	Gets the font ascent in pixels.

IMPORT_C TInt	DescentInPixels () const
	Gets the font descent in pixels.

IMPORT_C TInt	CharWidthInPixels (TChar aChar) const
	Gets the width in pixels in this font of the specified character.

IMPORT_C TInt	TextWidthInPixels (const TDesC &aText) const
	Gets the width in pixels of the specified descriptor when displayed in this font.

IMPORT_C TInt	BaselineOffsetInPixels () const
	Gets the baseline offset in pixels.

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.

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.

IMPORT_C TInt	MaxCharWidthInPixels () const
	Gets the width in pixels of the widest character in this font.

IMPORT_C TInt	MaxNormalCharWidthInPixels () const
	Gets the width in pixels of the widest normal character in this font.

IMPORT_C TFontSpec	FontSpecInTwips () const
	Gets the font specification of this font in twips.

IMPORT_C TCharacterDataAvailability	GetCharacterData (TUint aCode, TOpenFontCharMetrics &aMetrics, const TUint8 *&aBitmap, TSize &aBitmapSize) const
	Gets the character metrics for a character.

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.

IMPORT_C TInt	WidthZeroInPixels () const
	Gets the width of the zero character of this font in pixels.

IMPORT_C TInt	MeasureText (const TDesC &aText, const TMeasureTextInput aInput=NULL, TMeasureTextOutput aOutput=NULL) const
	Text measurement function.

IMPORT_C TInt	ExtendedFunction (TUid aFunctionId, TAny *aParam=NULL) const
	Enables the caller to access a particular API extension function.

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.

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.

Public Member Functions inherited from CBase
	CBase ()
	Default constructor.

virtual IMPORT_C	~CBase ()
	Virtual destructor.

TAny *	operator new (TUint aSize, TAny *aBase) __NO_THROW
	Initialises the object to binary zeroes.

TAny *	operator new (TUint aSize) __NO_THROW
	Allocates the object from the heap and then initialises its contents to binary zeroes.

TAny *	operator new (TUint aSize, TLeave)
	Allocates the object from the heap and then initialises its contents to binary zeroes.

TAny *	operator new (TUint aSize, TUint aExtraSize) __NO_THROW
	Allocates the object from the heap and then initialises its contents to binary zeroes.

TAny *	operator new (TUint aSize, TLeave, TUint aExtraSize)
	Allocates the object from the heap and then initialises its contents to binary zeroes.

Static Public Member Functions
static IMPORT_C TBool	CharactersJoin (TInt aLeftCharacter, TInt aRightCharacter)
	Determines if aLeftCharacter and aRightCharacter affect each other's contextual glyph form if placed next to each other.

Static Public Member Functions inherited from CBase
static IMPORT_C void	Delete (CBase *aPtr)
	Deletes the specified object.

Protected Member Functions
virtual IMPORT_C TCharacterDataAvailability	DoGetCharacterData (TUint aCode, TOpenFontCharMetrics &aMetrics, const TUint8 *&aBitmap, TSize &aBitmapSize) const
	Gets the character metrics for a character.

virtual IMPORT_C TBool	DoGetCharacterPosition (TPositionParam &aParam) const
	Overridable function innards of GetCharacterPosition and GetCharacterPosition2.

virtual IMPORT_C TInt	DoExtendedFunction (TUid aFunctionId, TAny *aParam=NULL) const
	API extension system that enables the caller to access a particular API extension function.

virtual IMPORT_C	~CFont ()
	Default destructor.

Protected Member Functions inherited from CBase
virtual IMPORT_C TInt	Extension_ (TUint aExtensionId, TAny &a0, TAny a1)
	Extension function.

Friends
class	CTypefaceStore

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()

API status: Published to all clients. Released API.

Definition at line 1346 of file gdi.h.

Member Enumeration Documentation

◆ TCharacterDataAvailability

enum CFont::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.

@see GetCharacterData()

API status: Published to all clients. Released API.

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

Definition at line 1577 of file gdi.h.

◆ TTextDirection

enum CFont::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.

See also: TMeasureTextInput

Enumerator

EHorizontal

Text is drawn horizontally.

EVertical

Text is drawn vertically.

Definition at line 1358 of file gdi.h.

Constructor & Destructor Documentation

◆ ~CFont()

IMPORT_C CFont::~CFont ( )

protectedvirtual

Default destructor.

(generated from Symbian Developer Library)

Member Function Documentation

◆ AscentInPixels()

IMPORT_C TInt CFont::AscentInPixels ( ) const

Gets the font ascent in pixels.

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

Returns: The font ascent in pixels.

See also: FontCapitalAscent(); FontMaxAscent()

Deprecated:

◆ BaselineOffsetInPixels()

IMPORT_C TInt CFont::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.

◆ CharactersJoin()

static IMPORT_C TBool CFont::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.

Parameters

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

(generated from Symbian Developer Library)

◆ CharWidthInPixels()

IMPORT_C TInt CFont::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.

Parameters

aChar The character whose width should be determined.

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

◆ DescentInPixels()

IMPORT_C TInt CFont::DescentInPixels ( ) const

Gets the font descent in pixels.

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

Returns: The font descent in pixels.

See also: FontStandardDescent(); FontMaxDescent()

Deprecated:

◆ DoExtendedFunction()

IMPORT_C TInt CFont::DoExtendedFunction	(	TUid	aFunctionId,
		TAny *	aParam = `NULL`
	)		const

protectedvirtual

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.

Parameters

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.

(generated from Symbian Developer Library)

◆ DoGetCharacterData()

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

protectedvirtual

Gets the character metrics for a character.

Parameters

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).

(generated from Symbian Developer Library)

◆ DoGetCharacterPosition()

IMPORT_C TBool CFont::DoGetCharacterPosition ( TPositionParam & aParam ) const

protectedvirtual

Overridable function innards of GetCharacterPosition and GetCharacterPosition2.

It is generally not useful to override this function. GetCharacterPosition GetCharacterPosition2

(generated from Symbian Developer Library)

◆ ExtendedFunction()

IMPORT_C TInt CFont::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.

Parameters

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.

(generated from Symbian Developer Library)

◆ FontCapitalAscent()

TInt CFont::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.

(generated from Symbian Developer Library)

◆ FontLineGap()

TInt CFont::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.

(generated from Symbian Developer Library)

◆ FontMaxAscent()

TInt CFont::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.

(generated from Symbian Developer Library)

◆ FontMaxDescent()

TInt CFont::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.

(generated from Symbian Developer Library)

◆ FontMaxHeight()

TInt CFont::FontMaxHeight ( ) const

inline

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

This may differ from the design height.

(generated from Symbian Developer Library)

◆ FontSpecInTwips()

IMPORT_C TFontSpec CFont::FontSpecInTwips ( ) const

Gets the font specification of this font in twips.

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

◆ FontStandardDescent()

TInt CFont::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.

(generated from Symbian Developer Library)

◆ GetCharacterData()

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

Gets the character metrics for a character.

Parameters

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).

(generated from Symbian Developer Library)

◆ GetCharacterPosition()

IMPORT_C TBool CFont::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. GetCharacterPosition2

Parameters

aParam Input and output parameters

(generated from Symbian Developer Library)

◆ GetCharacterPosition2()

IMPORT_C TBool CFont::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.

CFont::TPositionParam

Parameters

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.

(generated from Symbian Developer Library)

◆ HeightInPixels()

IMPORT_C TInt CFont::HeightInPixels ( ) const

Gets the font height in pixels.

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

Returns: The font height in pixels.

See also: FontMaxHeight()

Deprecated:

◆ MaxCharWidthInPixels()

IMPORT_C TInt CFont::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 CFont::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()

IMPORT_C TInt CFont::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.

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.

Parameters

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

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

(generated from Symbian Developer Library)

◆ TextCount() [1/2]

IMPORT_C TInt CFont::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.

Parameters

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() [2/2]

IMPORT_C TInt CFont::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.

Parameters

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() [1/2]

IMPORT_C TInt CFont::TextWidthInPixels ( const TDesC & aText ) const

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

Parameters

aText The descriptor whose width should be determined.

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

◆ TextWidthInPixels() [2/2]

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

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

Parameters

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 CFont::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 CFont::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.

(generated from Symbian Developer Library)

Friends And Related Symbol Documentation

◆ CTypefaceStore

friend class CTypefaceStore

friend

Definition at line 1348 of file gdi.h.

The documentation for this class was generated from the following files:

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Detailed Description

Member Enumeration Documentation

◆ TCharacterDataAvailability

◆ TTextDirection

Constructor & Destructor Documentation

◆ ~CFont()

Member Function Documentation

◆ AscentInPixels()

◆ BaselineOffsetInPixels()

◆ CharactersJoin()

◆ CharWidthInPixels()

◆ DescentInPixels()

◆ DoExtendedFunction()

◆ DoGetCharacterData()

◆ DoGetCharacterPosition()

◆ ExtendedFunction()

◆ FontCapitalAscent()

◆ FontLineGap()

◆ FontMaxAscent()

◆ FontMaxDescent()

◆ FontMaxHeight()

◆ FontSpecInTwips()

◆ FontStandardDescent()

◆ GetCharacterData()

◆ GetCharacterPosition()

◆ GetCharacterPosition2()

◆ HeightInPixels()

◆ MaxCharWidthInPixels()

◆ MaxNormalCharWidthInPixels()

◆ MeasureText()

◆ TextCount() [1/2]

◆ TextCount() [2/2]

◆ TextWidthInPixels() [1/2]

◆ TextWidthInPixels() [2/2]

◆ TypeUid()

◆ WidthZeroInPixels()

Friends And Related Symbol Documentation

◆ CTypefaceStore